appium 2.0.0-beta.35 → 2.0.0-beta.37

package/lib/cli/extension-command.js

@@ -1,9 +1,9 @@
 /* eslint-disable no-console */
-
+import B from 'bluebird';
 import _ from 'lodash';
 import path from 'path';
-import {npm, fs, util, env} from '@appium/support';
-import {log, spinWith, RingBuffer} from './utils';
+import {npm, util, env, console} from '@appium/support';
+import {spinWith, RingBuffer} from './utils';
 import {SubProcess} from 'teen_process';
 import {
   INSTALL_TYPE_NPM,
@@ -44,49 +44,56 @@ class ExtensionCommand {
    * Build an ExtensionCommand
    * @param {ExtensionCommandOptions<ExtType>} opts
    */
-  constructor ({config, json}) {
+  constructor({config, json}) {
     this.config = config;
-    this.isJsonOutput = json;
+    this.log = new console.CliConsole({jsonMode: json});
+    this.isJsonOutput = Boolean(json);
   }
 
   /**
    * `driver` or `plugin`, depending on the `ExtensionConfig`.
    */
-  get type () {
+  get type() {
     return this.config.extensionType;
   }
 
+  /**
+   * Logs a message and returns an {@linkcode Error} to throw.
+   *
+   * For TS to understand that a function throws an exception, it must actually throw an exception--
+   * in other words, _calling_ a function which is guaranteed to throw an exception is not enough--
+   * nor is something like `@returns {never}` which does not imply a thrown exception.
+   * @param {string} message
+   * @protected
+   * @returns {Error}
+   */
+  _createFatalError(message) {
+    return new Error(this.log.decorate(message, 'error'));
+  }
+
   /**
    * Take a CLI parse and run an extension command based on its type
    *
    * @param {object} args - a key/value object with CLI flags and values
    * @return {Promise<object>} the result of the specific command which is executed
    */
-  async execute (args) {
+  async execute(args) {
     const cmd = args[`${this.type}Command`];
     if (!_.isFunction(this[cmd])) {
-      throw new Error(`Cannot handle ${this.type} command ${cmd}`);
+      throw this._createFatalError(`Cannot handle ${this.type} command ${cmd}`);
     }
     const executeCmd = this[cmd].bind(this);
     return await executeCmd(args);
   }
 
-  /**
-   * @typedef ListOptions
-   * @property {boolean} showInstalled - whether should show only installed extensions
-   * @property {boolean} showUpdates - whether should show available updates
-   */
-
   /**
    * List extensions
    *
    * @param {ListOptions} opts
    * @return {Promise<ExtensionListData>} map of extension names to extension data
    */
-  async list ({showInstalled, showUpdates}) {
-    const lsMsg = `Listing ${showInstalled ? 'installed' : 'available'} ${
-      this.type
-    }s`;
+  async list({showInstalled, showUpdates}) {
+    const lsMsg = `Listing ${showInstalled ? 'installed' : 'available'} ${this.type}s`;
     const installedNames = Object.keys(this.config.installedExtensions);
     const knownNames = Object.keys(this.knownExtensions);
     const exts = [...installedNames, ...knownNames].reduce(
@@ -124,8 +131,7 @@ class ExtensionCommand {
         const updates = await this.checkForExtensionUpdate(ext);
         data.updateVersion = updates.safeUpdate;
         data.unsafeUpdateVersion = updates.unsafeUpdate;
-        data.upToDate =
-          updates.safeUpdate === null && updates.unsafeUpdate === null;
+        data.upToDate = updates.safeUpdate === null && updates.unsafeUpdate === null;
       }
     });
 
@@ -143,14 +149,8 @@ class ExtensionCommand {
       let upToDateTxt = '';
       let unsafeUpdateTxt = '';
       if (data.installed) {
-        const {
-          installType,
-          installSpec,
-          updateVersion,
-          unsafeUpdateVersion,
-          version,
-          upToDate,
-        } = data;
+        const {installType, installSpec, updateVersion, unsafeUpdateVersion, version, upToDate} =
+          data;
         let typeTxt;
         switch (installType) {
           case INSTALL_TYPE_GIT:
@@ -163,9 +163,7 @@ class ExtensionCommand {
           default:
             typeTxt = '(NPM)';
         }
-        installTxt = `@${version.yellow} ${
-          ('[installed ' + typeTxt + ']').green
-        }`;
+        installTxt = `@${version.yellow} ${('[installed ' + typeTxt + ']').green}`;
 
         if (showUpdates) {
           if (updateVersion) {
@@ -175,15 +173,12 @@ class ExtensionCommand {
             upToDateTxt = ` [Up to date]`.green;
           }
           if (unsafeUpdateVersion) {
-            unsafeUpdateTxt =
-              ` [${unsafeUpdateVersion} available (potentially unsafe)]`.cyan;
+            unsafeUpdateTxt = ` [${unsafeUpdateVersion} available (potentially unsafe)]`.cyan;
           }
         }
       }
 
-      console.log(
-        `- ${name.yellow}${installTxt}${updateTxt}${upToDateTxt}${unsafeUpdateTxt}`
-      );
+      this.log.log(`- ${name.yellow}${installTxt}${updateTxt}${upToDateTxt}${unsafeUpdateTxt}`);
     }
 
     return listData;
@@ -195,53 +190,57 @@ class ExtensionCommand {
    * @param {InstallArgs} args
    * @return {Promise<ExtRecord<ExtType>>} map of all installed extension names to extension data
    */
-  async _install ({installSpec, installType, packageName}) {
-    /** @type {ExtensionFields<typeof this.type>} */
+  async _install({installSpec, installType, packageName}) {
+    /** @type {ExtensionFields<ExtType>} */
     let extData;
 
-    if (
-      packageName &&
-      [INSTALL_TYPE_LOCAL, INSTALL_TYPE_NPM].includes(installType)
-    ) {
-      throw new Error(
-        `When using --source=${installType}, cannot also use --package`
-      );
+    if (packageName && [INSTALL_TYPE_LOCAL, INSTALL_TYPE_NPM].includes(installType)) {
+      throw this._createFatalError(`When using --source=${installType}, cannot also use --package`);
     }
 
-    if (
-      !packageName &&
-      [INSTALL_TYPE_GIT, INSTALL_TYPE_GITHUB].includes(installType)
-    ) {
-      throw new Error(
-        `When using --source=${installType}, must also use --package`
-      );
+    if (!packageName && [INSTALL_TYPE_GIT, INSTALL_TYPE_GITHUB].includes(installType)) {
+      throw this._createFatalError(`When using --source=${installType}, must also use --package`);
     }
 
+    /**
+     * @type {InstallViaNpmArgs}
+     */
+    let installOpts;
+
+    /**
+     * The probable (?) name of the extension derived from the install spec.
+     *
+     * If using a local install type, this will remain empty.
+     * @type {string}
+     */
+    let probableExtName = '';
+
+    // depending on `installType`, build the options to pass into `installViaNpm`
     if (installType === INSTALL_TYPE_GITHUB) {
       if (installSpec.split('/').length !== 2) {
-        throw new Error(
+        throw this._createFatalError(
           `Github ${this.type} spec ${installSpec} appeared to be invalid; ` +
             'it should be of the form <org>/<repo>'
         );
       }
-      extData = await this.installViaNpm({
+      installOpts = {
         installSpec,
         pkgName: /** @type {string} */ (packageName),
-      });
+      };
+      probableExtName = installSpec;
     } else if (installType === INSTALL_TYPE_GIT) {
       // git urls can have '.git' at the end, but this is not necessary and would complicate the
       // way we download and name directories, so we can just remove it
       installSpec = installSpec.replace(/\.git$/, '');
-      extData = await this.installViaNpm({
+      installOpts = {
         installSpec,
         pkgName: /** @type {string} */ (packageName),
-      });
+      };
+      probableExtName = installSpec;
     } else {
       let pkgName, pkgVer;
       if (installType === INSTALL_TYPE_LOCAL) {
-        pkgName = path.isAbsolute(installSpec)
-          ? installSpec
-          : path.resolve(installSpec);
+        pkgName = path.isAbsolute(installSpec) ? installSpec : path.resolve(installSpec);
       } else {
         // at this point we have either an npm package or an appium verified extension
         // name or a local path. both of which will be installed via npm.
@@ -271,30 +270,68 @@ class ExtensionCommand {
             const msg =
               `Could not resolve ${this.type}; are you sure it's in the list ` +
               `of supported ${this.type}s? ${JSON.stringify(knownNames)}`;
-            throw new Error(msg);
+            throw this._createFatalError(msg);
           }
+          probableExtName = name;
           pkgName = this.knownExtensions[name];
           // given that we'll use the install type in the driver json, store it as
           // 'npm' now
           installType = INSTALL_TYPE_NPM;
         }
       }
+      installOpts = {installSpec, pkgName, pkgVer};
+    }
 
-      extData = await this.installViaNpm({installSpec, pkgName, pkgVer});
+    // fail fast here if we can
+    if (probableExtName && this.config.isInstalled(probableExtName)) {
+      throw this._createFatalError(
+        `A ${this.type} named "${probableExtName}" is already installed. ` +
+          `Did you mean to update? Run "appium ${this.type} update". See ` +
+          `installed ${this.type}s with "appium ${this.type} list --installed".`
+      );
     }
 
+    extData = await this.installViaNpm(installOpts);
+
+    // this _should_ be the same as `probablyExtName` as the one derived above unless
+    // install type is local.
     const extName = extData[/** @type {string} */ (`${this.type}Name`)];
-    delete extData[/** @type {string} */ (`${this.type}Name`)];
 
+    // check _a second time_ with the more-accurate extName
     if (this.config.isInstalled(extName)) {
-      throw new Error(
-        `A ${this.type} named '${extName}' is already installed. ` +
-          `Did you mean to update? 'appium ${this.type} update'. See ` +
-          `installed ${this.type}s with 'appium ${this.type} list --installed'.`
+      throw this._createFatalError(
+        `A ${this.type} named "${extName}" is already installed. ` +
+          `Did you mean to update? Run "appium ${this.type} update". See ` +
+          `installed ${this.type}s with "appium ${this.type} list --installed".`
       );
     }
 
+    // this field does not exist as such in the manifest (it's used as a property name instead)
+    // so that's why it's being removed here.
+    delete extData[/** @type {string} */ (`${this.type}Name`)];
+
+    /** @type {ExtManifest<ExtType>} */
     const extManifest = {...extData, installType, installSpec};
+    const [errors, warnings] = await B.all([
+      this.config.getProblems(extName, extManifest),
+      this.config.getWarnings(extName, extManifest),
+    ]);
+    const errorMap = new Map([[extName, errors]]);
+    const warningMap = new Map([[extName, warnings]]);
+    const {errorSummaries, warningSummaries} = this.config.getValidationResultSummaries(
+      errorMap,
+      warningMap
+    );
+
+    if (!_.isEmpty(errorSummaries)) {
+      throw this._createFatalError(errorSummaries.join('\n'));
+    }
+
+    // note that we won't show any warnings if there were errors.
+    if (!_.isEmpty(warningSummaries)) {
+      this.log.warn(warningSummaries.join('\n'));
+    }
+
     await this.config.addExtension(extName, extManifest);
 
     // update the if we've changed the local `package.json`
@@ -303,7 +340,7 @@ class ExtensionCommand {
     }
 
     // log info for the user
-    log(this.isJsonOutput, this.getPostInstallText({extName, extData}));
+    this.log.info(this.getPostInstallText({extName, extData}));
 
     return this.config.installedExtensions;
   }
@@ -313,25 +350,22 @@ class ExtensionCommand {
    *
    * @param {InstallViaNpmArgs} args
    */
-  async installViaNpm ({installSpec, pkgName, pkgVer}) {
+  async installViaNpm({installSpec, pkgName, pkgVer}) {
     const npmSpec = `${pkgName}${pkgVer ? '@' + pkgVer : ''}`;
-    const specMsg =
-      npmSpec === installSpec ? '' : ` using NPM install spec '${npmSpec}'`;
+    const specMsg = npmSpec === installSpec ? '' : ` using NPM install spec '${npmSpec}'`;
     const msg = `Installing '${installSpec}'${specMsg}`;
     try {
-      const pkgJsonData = await spinWith(
-        this.isJsonOutput,
-        msg,
-        async () =>
-          await npm.installPackage(this.config.appiumHome, pkgName, {
-            pkgVer,
-          })
-      );
-      return this.getExtensionFields(pkgJsonData, installSpec);
+      const pkgJsonData = await spinWith(this.isJsonOutput, msg, async () => {
+        const pkgJsonData = await npm.installPackage(this.config.appiumHome, pkgName, {
+          pkgVer,
+        });
+        this.validatePackageJson(pkgJsonData, installSpec);
+        return pkgJsonData;
+      });
+
+      return this.getExtensionFields(pkgJsonData);
     } catch (err) {
-      throw new Error(
-        `Encountered an error when installing package: ${err.message}`
-      );
+      throw this._createFatalError(`Encountered an error when installing package: ${err.message}`);
     }
   }
 
@@ -343,8 +377,8 @@ class ExtensionCommand {
    * @returns {string}
    */
   // eslint-disable-next-line no-unused-vars
-  getPostInstallText (args) {
-    throw new Error('Must be implemented in final class');
+  getPostInstallText(args) {
+    throw this._createFatalError('Must be implemented in final class');
   }
 
   /**
@@ -353,27 +387,61 @@ class ExtensionCommand {
    * load as the main driver class, or to be able to detect incompatibilities between driver and
    * appium versions.
    *
-   * @param {ExtPackageJson<ExtType>} pkgJsonData - the package.json data for a driver module, as if it had been straightforwardly 'require'd
-   * @param {string} installSpec
+   * @param {ExtPackageJson<ExtType>} pkgJson - the package.json data for a driver module, as if it had been straightforwardly 'require'd
    * @returns {ExtensionFields<ExtType>}
    */
-  getExtensionFields (pkgJsonData, installSpec) {
-    if (!pkgJsonData.appium) {
-      throw new Error(
-        `Installed driver did not have an 'appium' section in its ` +
-          `package.json file as expected`
-      );
-    }
-    const {appium, name, version} = pkgJsonData;
-    this.validateExtensionFields(appium, installSpec);
+  getExtensionFields(pkgJson) {
+    const {appium, name, version, peerDependencies} = pkgJson;
+
     /** @type {unknown} */
-    const result = {...appium, pkgName: name, version};
+    const result = {
+      ...appium,
+      pkgName: name,
+      version,
+      appiumVersion: peerDependencies?.appium,
+    };
     return /** @type {ExtensionFields<ExtType>} */ (result);
   }
 
   /**
-   * For any package.json fields which a particular type of extension requires, validate the
-   * presence and form of those fields on the package.json data, throwing an error if anything is
+   * Validates the _required_ root fields of an extension's `package.json` file.
+   *
+   * These required fields are:
+   * - `name`
+   * - `version`
+   * - `appium`
+   * @param {import('type-fest').PackageJson} pkgJson - `package.json` of extension
+   * @param {string} installSpec - Extension name/spec
+   * @throws {ReferenceError} If `package.json` has a missing or invalid field
+   * @returns {pkgJson is ExtPackageJson<ExtType>}
+   */
+  validatePackageJson(pkgJson, installSpec) {
+    const {appium, name, version} = /** @type {ExtPackageJson<ExtType>} */ (pkgJson);
+
+    /**
+     *
+     * @param {string} field
+     * @returns {ReferenceError}
+     */
+    const createMissingFieldError = (field) =>
+      new ReferenceError(
+        `${this.type} "${installSpec}" invalid; missing a \`${field}\` field of its \`package.json\``
+      );
+
+    if (!name) {
+      throw createMissingFieldError('name');
+    }
+    if (!version) {
+      throw createMissingFieldError('version');
+    }
+    if (!appium) {
+      throw createMissingFieldError('appium');
+    }
+
+    this.validateExtensionFields(appium, installSpec);
+
+    return true;
+  }
 
   /**
    * For any `package.json` fields which a particular type of extension requires, validate the
@@ -384,32 +452,30 @@ class ExtensionCommand {
    * @param {string} installSpec - Extension name/spec
    */
   // eslint-disable-next-line no-unused-vars
-  validateExtensionFields (extMetadata, installSpec) {
-    throw new Error('Must be implemented in final class');
+  validateExtensionFields(extMetadata, installSpec) {
+    throw this._createFatalError('Must be implemented in final class');
   }
 
   /**
-   * Uninstall an extension
+   * Uninstall an extension.
+   *
+   * First tries to do this via `npm uninstall`, but if that fails, just `rm -rf`'s the extension dir.
+   *
+   * Will only remove the extension from the manifest if it has been successfully removed.
    *
    * @param {UninstallOpts} opts
-   * @return {Promise<ExtRecord<ExtType>>} map of all installed extension names to extension data
+   * @return {Promise<ExtRecord<ExtType>>} map of all installed extension names to extension data (without the extension just uninstalled)
    */
-  async _uninstall ({installSpec}) {
+  async _uninstall({installSpec}) {
     if (!this.config.isInstalled(installSpec)) {
-      throw new Error(
+      throw this._createFatalError(
         `Can't uninstall ${this.type} '${installSpec}'; it is not installed`
       );
     }
-    const installPath = this.config.getInstallPath(installSpec);
-    try {
-      await fs.rimraf(installPath);
-    } finally {
-      await this.config.removeExtension(installSpec);
-    }
-    log(
-      this.isJsonOutput,
-      `Successfully uninstalled ${this.type} '${installSpec}'`.green
-    );
+    const pkgName = this.config.installedExtensions[installSpec].pkgName;
+    await npm.uninstallPackage(this.config.appiumHome, pkgName);
+    await this.config.removeExtension(installSpec);
+    this.log.ok(`Successfully uninstalled ${this.type} '${installSpec}'`.green);
     return this.config.installedExtensions;
   }
 
@@ -419,12 +485,12 @@ class ExtensionCommand {
    * @param {ExtensionUpdateOpts} updateSpec
    * @return {Promise<ExtensionUpdateResult>}
    */
-  async _update ({installSpec, unsafe}) {
+  async _update({installSpec, unsafe}) {
     const shouldUpdateAll = installSpec === UPDATE_ALL;
     // if we're specifically requesting an update for an extension, make sure it's installed
     if (!shouldUpdateAll && !this.config.isInstalled(installSpec)) {
-      throw new Error(
-        `The ${this.type} '${installSpec}' was not installed, so can't be updated`
+      throw this._createFatalError(
+        `The ${this.type} "${installSpec}" was not installed, so can't be updated`
       );
     }
     const extsToUpdate = shouldUpdateAll
@@ -442,18 +508,11 @@ class ExtensionCommand {
 
     for (const e of extsToUpdate) {
       try {
-        await spinWith(
-          this.isJsonOutput,
-          `Checking if ${this.type} '${e}' is updatable`,
-          () => {
-            if (
-              this.config.installedExtensions[e].installType !==
-              INSTALL_TYPE_NPM
-            ) {
-              throw new NotUpdatableError();
-            }
+        await spinWith(this.isJsonOutput, `Checking if ${this.type} '${e}' is updatable`, () => {
+          if (this.config.installedExtensions[e].installType !== INSTALL_TYPE_NPM) {
+            throw new NotUpdatableError();
           }
-        );
+        });
         const update = await spinWith(
           this.isJsonOutput,
           `Checking if ${this.type} '${e}' needs an update`,
@@ -466,16 +525,13 @@ class ExtensionCommand {
           }
         );
         if (!unsafe && !update.safeUpdate) {
-          throw new Error(
+          throw this._createFatalError(
             `The ${this.type} '${e}' has a major revision update ` +
               `(${update.current} => ${update.unsafeUpdate}), which could include ` +
               `breaking changes. If you want to apply this update, re-run with --unsafe`
           );
         }
-        const updateVer =
-          unsafe && update.unsafeUpdate
-            ? update.unsafeUpdate
-            : update.safeUpdate;
+        const updateVer = unsafe && update.unsafeUpdate ? update.unsafeUpdate : update.safeUpdate;
         await spinWith(
           this.isJsonOutput,
           `Updating driver '${e}' from ${update.current} to ${updateVer}`,
@@ -487,28 +543,24 @@ class ExtensionCommand {
       }
     }
 
-    log(this.isJsonOutput, 'Update report:');
+    this.log.info('Update report:');
+
     for (const [e, update] of _.toPairs(updates)) {
-      log(
-        this.isJsonOutput,
-        `- ${this.type} ${e} updated: ${update.from} => ${update.to}`.green
-      );
+      this.log.ok(`  - ${this.type} ${e} updated: ${update.from} => ${update.to}`.green);
     }
+
     for (const [e, err] of _.toPairs(errors)) {
       if (err instanceof NotUpdatableError) {
-        log(
-          this.isJsonOutput,
-          `- '${e}' was not installed via npm, so we could not check ` +
-            `for updates`.yellow
+        this.log.warn(
+          `  - '${e}' was not installed via npm, so we could not check ` + `for updates`.yellow
         );
       } else if (err instanceof NoUpdatesAvailableError) {
-        log(this.isJsonOutput, `- '${e}' had no updates available`.yellow);
+        this.log.info(`  - '${e}' had no updates available`.yellow);
       } else {
         // otherwise, make it pop with red!
-        log(this.isJsonOutput, `- '${e}' failed to update: ${err}`.red);
+        this.log.error(`  - '${e}' failed to update: ${err}`.red);
       }
     }
-
     return {updates, errors};
   }
 
@@ -519,15 +571,12 @@ class ExtensionCommand {
    * @param {string} ext - name of extension
    * @return {Promise<PossibleUpdates>}
    */
-  async checkForExtensionUpdate (ext) {
+  async checkForExtensionUpdate(ext) {
     // TODO decide how we want to handle beta versions?
     // this is a helper method, 'ext' is assumed to already be installed here, and of the npm
     // install type
     const {version, pkgName} = this.config.installedExtensions[ext];
-    let unsafeUpdate = await npm.getLatestVersion(
-      this.config.appiumHome,
-      pkgName
-    );
+    let unsafeUpdate = await npm.getLatestVersion(this.config.appiumHome, pkgName);
     let safeUpdate = await npm.getLatestSafeUpgradeVersion(
       this.config.appiumHome,
       pkgName,
@@ -557,9 +606,8 @@ class ExtensionCommand {
    * @param {string} version - version string identifier to update extension to
    * @returns {Promise<void>}
    */
-  async updateExtension (installSpec, version) {
+  async updateExtension(installSpec, version) {
     const {pkgName} = this.config.installedExtensions[installSpec];
-    await fs.rimraf(this.config.getInstallPath(installSpec));
     const extData = await this.installViaNpm({
       installSpec,
       pkgName,
@@ -580,16 +628,16 @@ class ExtensionCommand {
    * @param {RunOptions} opts
    * @return {Promise<RunOutput>}
    */
-  async _run ({installSpec, scriptName}) {
-    if (!_.has(this.config.installedExtensions, installSpec)) {
-      throw new Error(`please install the ${this.type} first`);
+  async _run({installSpec, scriptName}) {
+    if (!this.config.isInstalled(installSpec)) {
+      throw this._createFatalError(`The ${this.type} "${installSpec}" is not installed`);
     }
 
     const extConfig = this.config.installedExtensions[installSpec];
 
     // note: TS cannot understand that _.has() is a type guard
     if (!extConfig.scripts) {
-      throw new Error(
+      throw this._createFatalError(
         `The ${this.type} named '${installSpec}' does not contain the ` +
           `"scripts" field underneath the "appium" field in its package.json`
       );
@@ -598,13 +646,13 @@ class ExtensionCommand {
     const extScripts = extConfig.scripts;
 
     if (!_.isPlainObject(extScripts)) {
-      throw new Error(
+      throw this._createFatalError(
         `The ${this.type} named '${installSpec}' "scripts" field must be a plain object`
       );
     }
 
     if (!_.has(extScripts, scriptName)) {
-      throw new Error(
+      throw this._createFatalError(
         `The ${this.type} named '${installSpec}' does not support the script: '${scriptName}'`
       );
     }
@@ -617,20 +665,17 @@ class ExtensionCommand {
 
     runner.on('stream-line', (line) => {
       output.enqueue(line);
-      log(this.isJsonOutput, line);
+      this.log.log(line);
     });
 
     await runner.start(0);
 
     try {
       await runner.join();
-      log(this.isJsonOutput, `${scriptName} successfully ran`.green);
+      this.log.ok(`${scriptName} successfully ran`.green);
       return {output: output.getBuff()};
     } catch (err) {
-      log(
-        this.isJsonOutput,
-        `Encountered an error when running '${scriptName}': ${err.message}`.red
-      );
+      this.log.error(`Encountered an error when running '${scriptName}': ${err.message}`.red);
       return {error: err.message, output: output.getBuff()};
     }
   }
@@ -658,14 +703,14 @@ export {ExtensionCommand};
  */
 
 /**
- * @typedef {import('../../types').ExtensionType} ExtensionType
- * @typedef {import('../../types').DriverType} DriverType
- * @typedef {import('../../types').PluginType} PluginType
+ * @typedef {import('@appium/types').ExtensionType} ExtensionType
+ * @typedef {import('@appium/types').DriverType} DriverType
+ * @typedef {import('@appium/types').PluginType} PluginType
  */
 
 /**
  * @template {ExtensionType} ExtType
- * @typedef {import('../../types/appium-manifest').ExtRecord<ExtType>} ExtRecord
+ * @typedef {import('appium/types').ExtRecord<ExtType>} ExtRecord
  */
 
 /**
@@ -675,17 +720,17 @@ export {ExtensionCommand};
 
 /**
  * @template {ExtensionType} ExtType
- * @typedef {import('../../types/external-manifest').ExtMetadata<ExtType>} ExtMetadata
+ * @typedef {import('appium/types').ExtMetadata<ExtType>} ExtMetadata
  */
 
 /**
  * @template {ExtensionType} ExtType
- * @typedef {import('../../types/appium-manifest').ExtManifest<ExtType>} ExtManifest
+ * @typedef {import('appium/types').ExtManifest<ExtType>} ExtManifest
  */
 
 /**
  * @template {ExtensionType} ExtType
- * @typedef {import('../../types/external-manifest').ExtPackageJson<ExtType>} ExtPackageJson
+ * @typedef {import('appium/types').ExtPackageJson<ExtType>} ExtPackageJson
  */
 
 /**
@@ -697,7 +742,7 @@ export {ExtensionCommand};
 
 /**
  * Possible return value for {@linkcode ExtensionCommand.list}
- * @typedef {import('../../types/appium-manifest').InternalMetadata & ExtensionMetadata} InstalledExtensionListData
+ * @typedef {import('appium/types').InternalMetadata & ExtensionMetadata} InstalledExtensionListData
  */
 
 /**
@@ -774,17 +819,23 @@ export {ExtensionCommand};
  * Options for {@linkcode ExtensionCommand._install}
  * @typedef InstallArgs
  * @property {string} installSpec - the name or spec of an extension to install
- * @property {import('../../types/appium-manifest').InstallType} installType - how to install this extension. One of the INSTALL_TYPES
+ * @property {import('appium/types').InstallType} installType - how to install this extension. One of the INSTALL_TYPES
  * @property {string} [packageName] - for git/github installs, the extension node package name
  */
 
 /**
  * Returned by {@linkcode ExtensionCommand.getExtensionFields}
  * @template {ExtensionType} ExtType
- * @typedef {ExtMetadata<ExtType> & { pkgName: string, version: string } & import('../../types/external-manifest').CommonMetadata} ExtensionFields
+ * @typedef {ExtMetadata<ExtType> & { pkgName: string, version: string, appiumVersion: string } & import('appium/types').CommonExtMetadata} ExtensionFields
  */
 
 /**
  * @template {ExtensionType} ExtType
  * @typedef {ExtType extends DriverType ? typeof import('../constants').KNOWN_DRIVERS : ExtType extends PluginType ? typeof import('../constants').KNOWN_PLUGINS : never} KnownExtensions
  */
+
+/**
+ * @typedef ListOptions
+ * @property {boolean} showInstalled - whether should show only installed extensions
+ * @property {boolean} showUpdates - whether should show available updates
+ */