appium 2.0.0-beta.34 → 2.0.0-beta.38

package/lib/cli/extension-command.js

@@ -1,13 +1,17 @@
 /* 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 { SubProcess } from 'teen_process';
-import { INSTALL_TYPE_NPM, INSTALL_TYPE_GIT, INSTALL_TYPE_GITHUB,
-         INSTALL_TYPE_LOCAL } from '../extension/extension-config';
-import { packageDidChange } from '../extension/package-changed';
+import {npm, util, env, console} from '@appium/support';
+import {spinWith, RingBuffer} from './utils';
+import {SubProcess} from 'teen_process';
+import {
+  INSTALL_TYPE_NPM,
+  INSTALL_TYPE_GIT,
+  INSTALL_TYPE_GITHUB,
+  INSTALL_TYPE_LOCAL,
+} from '../extension/extension-config';
+import {packageDidChange} from '../extension/package-changed';
 
 const UPDATE_ALL = 'installed';
 
@@ -40,64 +44,78 @@ 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}) {
+  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((acc, name) => {
-      if (!acc[name]) {
-        if (installedNames.includes(name)) {
-          acc[name] = {...this.config.installedExtensions[name], installed: true};
-        } else if (!showInstalled) {
-          acc[name] = {pkgName: this.knownExtensions[name], installed: false};
+    const exts = [...installedNames, ...knownNames].reduce(
+      (acc, name) => {
+        if (!acc[name]) {
+          if (installedNames.includes(name)) {
+            acc[name] = {
+              ...this.config.installedExtensions[name],
+              installed: true,
+            };
+          } else if (!showInstalled) {
+            acc[name] = {pkgName: this.knownExtensions[name], installed: false};
+          }
         }
-      }
-      return acc;
-    },
-    /**
-     * This accumulator contains either {@linkcode UninstalledExtensionLIstData} _or_
-     * {@linkcode InstalledExtensionListData} without upgrade information (which is added by the below code block)
-     * @type {Record<string,Partial<InstalledExtensionListData>|UninstalledExtensionListData>}
-     */({}));
+        return acc;
+      },
+      /**
+       * This accumulator contains either {@linkcode UninstalledExtensionLIstData} _or_
+       * {@linkcode InstalledExtensionListData} without upgrade information (which is added by the below code block)
+       * @type {Record<string,Partial<InstalledExtensionListData>|UninstalledExtensionListData>}
+       */ ({})
+    );
 
     // if we want to show whether updates are available, put that behind a spinner
     await spinWith(this.isJsonOutput, lsMsg, async () => {
@@ -117,7 +135,7 @@ class ExtensionCommand {
       }
     });
 
-    const listData = /** @type {ExtensionListData} */(exts);
+    const listData = /** @type {ExtensionListData} */ (exts);
 
     // if we're just getting the data, short circuit return here since we don't need to do any
     // formatting logic
@@ -125,16 +143,14 @@ class ExtensionCommand {
       return listData;
     }
 
-    for (const [
-      name,
-      data
-    ] of _.toPairs(listData)) {
+    for (const [name, data] of _.toPairs(listData)) {
       let installTxt = ' [not installed]'.grey;
       let updateTxt = '';
       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:
@@ -162,7 +178,7 @@ class ExtensionCommand {
         }
       }
 
-      console.log(`- ${name.yellow}${installTxt}${updateTxt}${upToDateTxt}${unsafeUpdateTxt}`);
+      this.log.log(`- ${name.yellow}${installTxt}${updateTxt}${upToDateTxt}${unsafeUpdateTxt}`);
     }
 
     return listData;
@@ -174,29 +190,53 @@ class ExtensionCommand {
    * @param {InstallArgs} args
    * @return {Promise<ExtRecord<ExtType>>} map of all installed extension names to extension data
    */
-  async _install ({ext, installType, packageName}) {
+  async _install({installSpec, installType, packageName}) {
+    /** @type {ExtensionFields<ExtType>} */
     let extData;
-    let installSpec = ext;
 
     if (packageName && [INSTALL_TYPE_LOCAL, INSTALL_TYPE_NPM].includes(installType)) {
-      throw new Error(`When using --source=${installType}, cannot also use --package`);
+      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`);
+      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(`Github ${this.type} spec ${installSpec} appeared to be invalid; ` +
-                        'it should be of the form <org>/<repo>');
+        throw this._createFatalError(
+          `Github ${this.type} spec ${installSpec} appeared to be invalid; ` +
+            'it should be of the form <org>/<repo>'
+        );
       }
-      extData = await this.installViaNpm({ext: installSpec, pkgName: /** @type {string} */(packageName)});
+      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({ext: installSpec, pkgName: /** @type {string} */(packageName)});
+      installOpts = {
+        installSpec,
+        pkgName: /** @type {string} */ (packageName),
+      };
+      probableExtName = installSpec;
     } else {
       let pkgName, pkgVer;
       if (installType === INSTALL_TYPE_LOCAL) {
@@ -227,30 +267,71 @@ class ExtensionCommand {
           // check it exists and get the correct package
           const knownNames = Object.keys(this.knownExtensions);
           if (!_.includes(knownNames, name)) {
-            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);
+            const msg =
+              `Could not resolve ${this.type}; are you sure it's in the list ` +
+              `of supported ${this.type}s? ${JSON.stringify(knownNames)}`;
+            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({ext, 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".`
+      );
     }
 
-    const extName = extData[/** @type {string} */(`${this.type}Name`)];
-    delete extData[/** @type {string} */(`${this.type}Name`)];
+    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`)];
 
+    // 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`
@@ -259,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;
   }
@@ -269,19 +350,22 @@ class ExtensionCommand {
    *
    * @param {InstallViaNpmArgs} args
    */
-  async installViaNpm ({ext, pkgName, pkgVer}) {
+  async installViaNpm({installSpec, pkgName, pkgVer}) {
     const npmSpec = `${pkgName}${pkgVer ? '@' + pkgVer : ''}`;
-    const specMsg = npmSpec === ext ? '' : ` using NPM install spec '${npmSpec}'`;
-    const msg = `Installing '${ext}'${specMsg}`;
+    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
-        })
-      ));
+      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}`);
     }
   }
 
@@ -293,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');
   }
 
   /**
@@ -303,51 +387,95 @@ 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 {ExtPackageJson<ExtType>} pkgJson - the package.json data for a driver module, as if it had been straightforwardly 'require'd
    * @returns {ExtensionFields<ExtType>}
    */
-  getExtensionFields (pkgJsonData) {
-    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);
+  getExtensionFields(pkgJson) {
+    const {appium, name, version, peerDependencies} = pkgJson;
+
     /** @type {unknown} */
-    const result = {...appium, pkgName: name, version};
-    return /** @type {ExtensionFields<ExtType>} */(result);
+    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
+   * presence and form of those fields on the `package.json` data, throwing an error if anything is
    * amiss.
    *
-   * @param {ExtMetadata<ExtType>} appiumPkgData - the data in the "appium" field of package.json for an extension
+   * @param {ExtMetadata<ExtType>} extMetadata - the data in the "appium" field of `package.json` for an extension
+   * @param {string} installSpec - Extension name/spec
    */
   // eslint-disable-next-line no-unused-vars
-  validateExtensionFields (appiumPkgData) {
-    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 ({ext}) {
-    if (!this.config.isInstalled(ext)) {
-      throw new Error(`Can't uninstall ${this.type} '${ext}'; it is not installed`);
+  async _uninstall({installSpec}) {
+    if (!this.config.isInstalled(installSpec)) {
+      throw this._createFatalError(
+        `Can't uninstall ${this.type} '${installSpec}'; it is not installed`
+      );
     }
-    const installPath = this.config.getInstallPath(ext);
-    try {
-      await fs.rimraf(installPath);
-    } finally {
-      await this.config.removeExtension(ext);
-    }
-    log(this.isJsonOutput, `Successfully uninstalled ${this.type} '${ext}'`.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;
   }
 
@@ -357,13 +485,17 @@ class ExtensionCommand {
    * @param {ExtensionUpdateOpts} updateSpec
    * @return {Promise<ExtensionUpdateResult>}
    */
-  async _update ({ext, unsafe}) {
-    const shouldUpdateAll = ext === UPDATE_ALL;
+  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(ext)) {
-      throw new Error(`The ${this.type} '${ext}' was not installed, so can't be updated`);
+    if (!shouldUpdateAll && !this.config.isInstalled(installSpec)) {
+      throw this._createFatalError(
+        `The ${this.type} "${installSpec}" was not installed, so can't be updated`
+      );
     }
-    const extsToUpdate = shouldUpdateAll ? Object.keys(this.config.installedExtensions) : [ext];
+    const extsToUpdate = shouldUpdateAll
+      ? Object.keys(this.config.installedExtensions)
+      : [installSpec];
 
     // 'errors' will have ext names as keys and error objects as values
     /** @type {Record<string,Error>} */
@@ -381,17 +513,23 @@ class ExtensionCommand {
             throw new NotUpdatableError();
           }
         });
-        const update = await spinWith(this.isJsonOutput, `Checking if ${this.type} '${e}' needs an update`, async () => {
-          const update = await this.checkForExtensionUpdate(e);
-          if (!(update.safeUpdate || update.unsafeUpdate)) {
-            throw new NoUpdatesAvailableError();
+        const update = await spinWith(
+          this.isJsonOutput,
+          `Checking if ${this.type} '${e}' needs an update`,
+          async () => {
+            const update = await this.checkForExtensionUpdate(e);
+            if (!(update.safeUpdate || update.unsafeUpdate)) {
+              throw new NoUpdatesAvailableError();
+            }
+            return update;
           }
-          return update;
-        });
+        );
         if (!unsafe && !update.safeUpdate) {
-          throw new Error(`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`);
+          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;
         await spinWith(
@@ -405,22 +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};
   }
 
@@ -431,13 +571,17 @@ 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 safeUpdate = await npm.getLatestSafeUpgradeVersion(this.config.appiumHome, pkgName, version);
+    let safeUpdate = await npm.getLatestSafeUpgradeVersion(
+      this.config.appiumHome,
+      pkgName,
+      version
+    );
     if (!util.compareVersions(unsafeUpdate, '>', version)) {
       // the latest version is not greater than the current version, so there's no possible update
       unsafeUpdate = null;
@@ -458,16 +602,19 @@ class ExtensionCommand {
    * Actually update an extension installed by NPM, using the NPM cli. And update the installation
    * manifest.
    *
-   * @param {string} ext - name of extension to update
+   * @param {string} installSpec - name of extension to update
    * @param {string} version - version string identifier to update extension to
    * @returns {Promise<void>}
    */
-  async updateExtension (ext, version) {
-    const {pkgName} = this.config.installedExtensions[ext];
-    await fs.rimraf(this.config.getInstallPath(ext));
-    const extData = await this.installViaNpm({ext, pkgName, pkgVer: version});
-    delete extData[/** @type {string} */(`${this.type}Name`)];
-    await this.config.updateExtension(ext, extData);
+  async updateExtension(installSpec, version) {
+    const {pkgName} = this.config.installedExtensions[installSpec];
+    const extData = await this.installViaNpm({
+      installSpec,
+      pkgName,
+      pkgVer: version,
+    });
+    delete extData[/** @type {string} */ (`${this.type}Name`)];
+    await this.config.updateExtension(installSpec, extData);
   }
 
   /**
@@ -481,50 +628,54 @@ class ExtensionCommand {
    * @param {RunOptions} opts
    * @return {Promise<RunOutput>}
    */
-  async _run ({ext, scriptName}) {
-    if (!_.has(this.config.installedExtensions, ext)) {
-      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[ext];
+    const extConfig = this.config.installedExtensions[installSpec];
 
     // note: TS cannot understand that _.has() is a type guard
     if (!extConfig.scripts) {
-      throw new Error(`The ${this.type} named '${ext}' does not contain the ` +
-                      `"scripts" field underneath the "appium" field in its package.json`);
+      throw this._createFatalError(
+        `The ${this.type} named '${installSpec}' does not contain the ` +
+          `"scripts" field underneath the "appium" field in its package.json`
+      );
     }
 
     const extScripts = extConfig.scripts;
 
     if (!_.isPlainObject(extScripts)) {
-      throw new Error(`The ${this.type} named '${ext}' "scripts" field must be a plain object`);
+      throw this._createFatalError(
+        `The ${this.type} named '${installSpec}' "scripts" field must be a plain object`
+      );
     }
 
     if (!_.has(extScripts, scriptName)) {
-      throw new Error(`The ${this.type} named '${ext}' does not support the script: '${scriptName}'`);
+      throw this._createFatalError(
+        `The ${this.type} named '${installSpec}' does not support the script: '${scriptName}'`
+      );
     }
 
-    const runner = new SubProcess(process.execPath, [
-      extScripts[scriptName]
-    ], {
-      cwd: this.config.getInstallPath(ext)
+    const runner = new SubProcess(process.execPath, [extScripts[scriptName]], {
+      cwd: this.config.getInstallPath(installSpec),
     });
 
     const output = new RingBuffer(50);
 
     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()};
     }
   }
@@ -552,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
  */
 
 /**
@@ -569,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
  */
 
 /**
@@ -591,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
  */
 
 /**
@@ -602,7 +753,7 @@ export {ExtensionCommand};
 /**
  * Options for {@linkcode ExtensionCommand._run}.
  * @typedef RunOptions
- * @property {string} ext - name of the extension to run a script from
+ * @property {string} installSpec - name of the extension to run a script from
  * @property {string} scriptName - name of the script to run
  */
 
@@ -617,7 +768,7 @@ export {ExtensionCommand};
 /**
  * Options for {@linkcode ExtensionCommand._update}.
  * @typedef ExtensionUpdateOpts
- * @property {string} ext - the name of the extension to update
+ * @property {string} installSpec - the name of the extension to update
  * @property {boolean} unsafe - if true, will perform unsafe updates past major revision boundaries
  */
 
@@ -638,7 +789,7 @@ export {ExtensionCommand};
 /**
  * Options for {@linkcode ExtensionCommand._uninstall}.
  * @typedef UninstallOpts
- * @property {string} ext - the name or spec of an extension to uninstall
+ * @property {string} installSpec - the name or spec of an extension to uninstall
  */
 
 /**
@@ -651,7 +802,7 @@ export {ExtensionCommand};
 /**
  * Options for {@linkcode ExtensionCommand.installViaNpm}
  * @typedef InstallViaNpmArgs
- * @property {string} ext - the name or spec of an extension to install
+ * @property {string} installSpec - the name or spec of an extension to install
  * @property {string} pkgName - the NPM package name of the extension
  * @property {string} [pkgVer] - the specific version of the NPM package
  */
@@ -667,18 +818,24 @@ export {ExtensionCommand};
 /**
  * Options for {@linkcode ExtensionCommand._install}
  * @typedef InstallArgs
- * @property {string} ext - 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 {string} installSpec - the name or spec of an extension to install
+ * @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
+ */