appium 2.0.0-beta.3 → 2.0.0-beta.30

package/lib/cli/extension-command.js

@@ -1,50 +1,66 @@
 /* eslint-disable no-console */
 
 import _ from 'lodash';
-import NPM from './npm';
 import path from 'path';
-import { fs, util } from 'appium-support';
-import { log, spinWith } from './utils';
+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-config';
+         INSTALL_TYPE_LOCAL } from '../extension/extension-config';
+import { packageDidChange } from '../extension/package-changed';
 
 const UPDATE_ALL = 'installed';
 
 class NotUpdatableError extends Error {}
 class NoUpdatesAvailableError extends Error {}
 
-export default class ExtensionCommand {
+/**
+ * @template {ExtensionType} ExtType
+ */
+class ExtensionCommand {
+  /**
+   * This is the `DriverConfig` or `PluginConfig`, depending on `ExtType`.
+   * @type {ExtensionConfig<ExtType>}
+   */
+  config;
+
+  /**
+   * {@linkcode Record} of official plugins or drivers.
+   * @type {KnownExtensions<ExtType>}
+   */
+  knownExtensions;
 
   /**
-   * @typedef {Object} ExtensionCommandConstructor
-   * @property {Object} config - the DriverConfig or PluginConfig object used for this command
-   * @property {boolean} json - whether the output of this command should be JSON or text
-   * @property {string} type - DRIVER_TYPE or PLUGIN_TYPE
+   * If `true`, command output has been requested as JSON.
+   * @type {boolean}
    */
+  isJsonOutput;
 
   /**
    * Build an ExtensionCommand
-   *
-   * @param {ExtensionCommandConstructor} opts
-   * @return {ExtensionCommand}
+   * @param {ExtensionCommandOptions<ExtType>} opts
    */
-  constructor ({config, json, type}) {
+  constructor ({config, json}) {
     this.config = config;
-    this.type = type;
     this.isJsonOutput = json;
-    this.npm = new NPM(this.config.appiumHome);
-    this.knownExtensions = {}; // this needs to be overridden in final class
+  }
+
+  /**
+   * `driver` or `plugin`, depending on the `ExtensionConfig`.
+   */
+  get type () {
+    return this.config.extensionType;
   }
 
   /**
    * 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 {object} the result of the specific command which is executed
+   * @return {Promise<object>} the result of the specific command which is executed
    */
   async execute (args) {
     const cmd = args[`${this.type}Command`];
-    if (!_.isFunction(ExtensionCommand.prototype[cmd])) {
+    if (!_.isFunction(this[cmd])) {
       throw new Error(`Cannot handle ${this.type} command ${cmd}`);
     }
     const executeCmd = this[cmd].bind(this);
@@ -52,7 +68,7 @@ export default class ExtensionCommand {
   }
 
   /**
-   * @typedef {Object} ListArgs
+   * @typedef ListOptions
    * @property {boolean} showInstalled - whether should show only installed extensions
    * @property {boolean} showUpdates - whether should show available updates
    */
@@ -60,8 +76,8 @@ export default class ExtensionCommand {
   /**
    * List extensions
    *
-   * @param {ListArgs} args
-   * @return {object} map of extension names to extension data
+   * @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`;
@@ -76,7 +92,12 @@ export default class ExtensionCommand {
         }
       }
       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 () => {
@@ -84,8 +105,7 @@ export default class ExtensionCommand {
         return;
       }
       for (const [ext, data] of _.toPairs(exts)) {
-        const {installed, installType} = data;
-        if (!installed || installType !== INSTALL_TYPE_NPM) {
+        if (!data.installed || data.installType !== INSTALL_TYPE_NPM) {
           // don't need to check for updates on exts that aren't installed
           // also don't need to check for updates on non-npm exts
           continue;
@@ -97,63 +117,64 @@ export default class ExtensionCommand {
       }
     });
 
+    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
     if (this.isJsonOutput) {
-      return exts;
+      return listData;
     }
 
     for (const [
       name,
-      {installType, installSpec, installed, updateVersion, unsafeUpdateVersion, version, upToDate}
-    ] of _.toPairs(exts)) {
-      let typeTxt;
-      switch (installType) {
-        case INSTALL_TYPE_GIT:
-        case INSTALL_TYPE_GITHUB:
-          typeTxt = `(cloned from ${installSpec})`.yellow;
-          break;
-        case INSTALL_TYPE_LOCAL:
-          typeTxt = `(linked from ${installSpec})`.magenta;
-          break;
-        default:
-          typeTxt = '(NPM)';
+      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;
+        let typeTxt;
+        switch (installType) {
+          case INSTALL_TYPE_GIT:
+          case INSTALL_TYPE_GITHUB:
+            typeTxt = `(cloned from ${installSpec})`.yellow;
+            break;
+          case INSTALL_TYPE_LOCAL:
+            typeTxt = `(linked from ${installSpec})`.magenta;
+            break;
+          default:
+            typeTxt = '(NPM)';
+        }
+        installTxt = `@${version.yellow} ${('[installed ' + typeTxt + ']').green}`;
+
+        if (showUpdates) {
+          if (updateVersion) {
+            updateTxt = ` [${updateVersion} available]`.magenta;
+          }
+          if (upToDate) {
+            upToDateTxt = ` [Up to date]`.green;
+          }
+          if (unsafeUpdateVersion) {
+            unsafeUpdateTxt = ` [${unsafeUpdateVersion} available (potentially unsafe)]`.cyan;
+          }
+        }
       }
-      const installTxt = installed ?
-        `@${version.yellow} ${('[installed ' + typeTxt + ']').green}` :
-        ' [not installed]'.grey;
-      const updateTxt = showUpdates && updateVersion ?
-        ` [${updateVersion} available]`.magenta :
-        '';
-      const upToDateTxt = showUpdates && upToDate ?
-        ` [Up to date]`.green :
-        '';
-      const unsafeUpdateTxt = showUpdates && unsafeUpdateVersion ?
-        ` [${unsafeUpdateVersion} available (potentially unsafe)]`.cyan :
-        '';
 
       console.log(`- ${name.yellow}${installTxt}${updateTxt}${upToDateTxt}${unsafeUpdateTxt}`);
     }
 
-    return exts;
+    return listData;
   }
 
-  /**
-   * @typedef {Object} InstallArgs
-   * @property {string} ext - the name or spec of an extension to install
-   * @property {string} installType - how to install this extension. One of the INSTALL_TYPES
-   * @property {string} [packageName] - for git/github installs, the extension node package name
-   */
-
   /**
    * Install an extension
    *
    * @param {InstallArgs} args
-   * @return {object} map of all installed extension names to extension data
+   * @return {Promise<ExtRecord<ExtType>>} map of all installed extension names to extension data
    */
-  async install ({ext, installType, packageName}) {
-    log(this.isJsonOutput, `Attempting to find and install ${this.type} '${ext}'`);
-
+  async _install ({ext, installType, packageName}) {
     let extData;
     let installSpec = ext;
 
@@ -165,66 +186,63 @@ export default class ExtensionCommand {
       throw new Error(`When using --source=${installType}, must also use --package`);
     }
 
-    if (installType === INSTALL_TYPE_LOCAL) {
-      const msg = `Linking ${this.type} from local path`;
-      const pkgJsonData = await spinWith(this.isJsonOutput, msg, async () => (
-        await this.npm.linkPackage(installSpec))
-      );
-      extData = this.getExtensionFields(pkgJsonData);
-      extData.installPath = extData.pkgName;
-    } else if (installType === INSTALL_TYPE_GITHUB) {
+    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>');
       }
-      extData = await this.installViaNpm({ext: installSpec, pkgName: packageName});
+      extData = await this.installViaNpm({ext: installSpec, pkgName: /** @type {string} */(packageName)});
     } 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: packageName});
+      extData = await this.installViaNpm({ext: installSpec, pkgName: /** @type {string} */(packageName)});
     } else {
-      // at this point we have either an npm package or an appium verified extension
-      // name. both of which will be installed via npm.
-      // extensions installed via npm can include versions or tags after the '@'
-      // sign, so check for that. We also need to be careful that package names themselves can
-      // contain the '@' symbol, as in `npm install @appium/fake-driver@1.2.0`
-      let name, pkgVer;
-      const splits = installSpec.split('@');
-      if (installSpec[0] === '@') {
-        // this is the case where we have an npm org included in the package name
-        [name, pkgVer] = [`@${splits[1]}`, splits[2]];
+      let pkgName, pkgVer;
+      if (installType === INSTALL_TYPE_LOCAL) {
+        pkgName = path.isAbsolute(installSpec) ? installSpec : path.resolve(installSpec);
       } else {
-        // this is the case without an npm org
-        [name, pkgVer] = splits;
-      }
-      let pkgName;
+        // 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.
+        // extensions installed via npm can include versions or tags after the '@'
+        // sign, so check for that. We also need to be careful that package names themselves can
+        // contain the '@' symbol, as in `npm install @appium/fake-driver@1.2.0`
+        let name;
+        const splits = installSpec.split('@');
+        if (installSpec[0] === '@') {
+          // this is the case where we have an npm org included in the package name
+          [name, pkgVer] = [`@${splits[1]}`, splits[2]];
+        } else {
+          // this is the case without an npm org
+          [name, pkgVer] = splits;
+        }
 
-      if (installType === INSTALL_TYPE_NPM) {
-        // if we're installing a named package from npm, we don't need to check
-        // against the appium extension list; just use the installSpec as is
-        pkgName = name;
-      } else {
-        // if we're installing a named appium driver (like 'xcuitest') we need to
-        // dereference the actual npm package ('appiupm-xcuitest-driver'), so
-        // 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);
+        if (installType === INSTALL_TYPE_NPM) {
+          // if we're installing a named package from npm, we don't need to check
+          // against the appium extension list; just use the installSpec as is
+          pkgName = name;
+        } else {
+          // if we're installing a named appium driver (like 'xcuitest') we need to
+          // dereference the actual npm package ('appiupm-xcuitest-driver'), so
+          // 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);
+          }
+          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;
         }
-        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;
       }
 
       extData = await this.installViaNpm({ext, pkgName, pkgVer});
     }
 
-    const extName = extData[`${this.type}Name`];
-    delete extData[`${this.type}Name`];
+    const extName = extData[/** @type {string} */(`${this.type}Name`)];
+    delete extData[/** @type {string} */(`${this.type}Name`)];
 
     if (this.config.isInstalled(extName)) {
       throw new Error(`A ${this.type} named '${extName}' is already installed. ` +
@@ -232,9 +250,13 @@ export default class ExtensionCommand {
                       `installed ${this.type}s with 'appium ${this.type} list --installed'.`);
     }
 
-    extData.installType = installType;
-    extData.installSpec = installSpec;
-    await this.config.addExtension(extName, extData);
+    const extManifest = {...extData, installType, installSpec};
+    await this.config.addExtension(extName, extManifest);
+
+    // update the if we've changed the local `package.json`
+    if (await env.hasAppiumDependency(this.config.appiumHome)) {
+      await packageDidChange(this.config.appiumHome);
+    }
 
     // log info for the user
     log(this.isJsonOutput, this.getPostInstallText({extName, extData}));
@@ -242,13 +264,6 @@ export default class ExtensionCommand {
     return this.config.installedExtensions;
   }
 
-  /**
-   * @typedef {Object} InstallViaNpmArgs
-   * @property {string} ext - 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
-   */
-
   /**
    * Install an extension via NPM
    *
@@ -260,33 +275,25 @@ export default class ExtensionCommand {
     const msg = `Installing '${ext}'${specMsg}`;
     try {
       const pkgJsonData = await spinWith(this.isJsonOutput, msg, async () => (
-        await this.npm.installPackage({
-          pkgDir: path.resolve(this.config.appiumHome, pkgName),
-          pkgName,
+        await npm.installPackage(this.config.appiumHome, pkgName, {
           pkgVer
         })
       ));
-      const extData = this.getExtensionFields(pkgJsonData);
-      extData.installPath = pkgName;
-      return extData;
+      return this.getExtensionFields(pkgJsonData);
     } catch (err) {
       throw new Error(`Encountered an error when installing package: ${err.message}`);
     }
   }
 
-  /**
-   * @typedef {Object} ExtensionArgs
-   * @property {string} extName - the name of an extension
-   * @property {object} extData - the data for an installed extension
-   */
-
   /**
    * Get the text which should be displayed to the user after an extension has been installed. This
    * is designed to be overridden by drivers/plugins with their own particular text.
    *
    * @param {ExtensionArgs} args
+   * @returns {string}
    */
-  getPostInstallText (/*{extName, extData}*/) {
+  // eslint-disable-next-line no-unused-vars
+  getPostInstallText (args) {
     throw new Error('Must be implemented in final class');
   }
 
@@ -296,8 +303,9 @@ export default class ExtensionCommand {
    * load as the main driver class, or to be able to detect incompatibilities between driver and
    * appium versions.
    *
-   * @param {object} pkgJsonData - the package.json data for a driver module, as if it had been
+   * @param {ExtPackageJson<ExtType>} pkgJsonData - the package.json data for a driver module, as if it had been
    * straightforwardly 'require'd
+   * @returns {ExtensionFields<ExtType>}
    */
   getExtensionFields (pkgJsonData) {
     if (!pkgJsonData.appium) {
@@ -306,8 +314,9 @@ export default class ExtensionCommand {
     }
     const {appium, name, version} = pkgJsonData;
     this.validateExtensionFields(appium);
-
-    return {...appium, pkgName: name, version};
+    /** @type {unknown} */
+    const result = {...appium, pkgName: name, version};
+    return /** @type {ExtensionFields<ExtType>} */(result);
   }
 
   /**
@@ -315,30 +324,26 @@ export default class ExtensionCommand {
    * presence and form of those fields on the package.json data, throwing an error if anything is
    * amiss.
    *
-   * @param {object} appiumPkgData - the data in the "appium" field of package.json for an
-   * extension
+   * @param {ExtMetadata<ExtType>} appiumPkgData - the data in the "appium" field of package.json for an extension
    */
-  validateExtensionFields (/*appiumPkgData*/) {
+  // eslint-disable-next-line no-unused-vars
+  validateExtensionFields (appiumPkgData) {
     throw new Error('Must be implemented in final class');
   }
 
-  /**
-   * @typedef {Object} UninstallArgs
-   * @property {string} ext - the name or spec of an extension to uninstall
-   */
-
   /**
    * Uninstall an extension
    *
-   * @param {UninstallArgs} args
-   * @return {object} map of all installed extension names to extension data
+   * @param {UninstallOpts} opts
+   * @return {Promise<ExtRecord<ExtType>>} map of all installed extension names to extension data
    */
-  async uninstall ({ext}) {
+  async _uninstall ({ext}) {
     if (!this.config.isInstalled(ext)) {
       throw new Error(`Can't uninstall ${this.type} '${ext}'; it is not installed`);
     }
+    const installPath = this.config.getInstallPath(ext);
     try {
-      await fs.rimraf(this.config.getInstallPath(ext));
+      await fs.rimraf(installPath);
     } finally {
       await this.config.removeExtension(ext);
     }
@@ -346,32 +351,13 @@ export default class ExtensionCommand {
     return this.config.installedExtensions;
   }
 
-  /**
-   * @typedef {Object} ExtensionUpdateOpts
-   * @property {string} ext - the name of the extension to update
-   * @property {boolean} unsafe - if true, will perform unsafe updates past major revision
-   * boundaries
-   */
-
-  /**
-   * @typedef {Object} UpdateReport
-   * @property {string} from - version updated from
-   * @property {string} to - version updated to
-   */
-
-  /**
-   * @typedef {Object} ExtensionUpdateResult
-   * @property {Object} errors - map of ext names to error objects
-   * @property {Object} updates - map of ext names to {@link UpdateReport}s
-   */
-
   /**
    * Attempt to update one or more drivers using NPM
    *
    * @param {ExtensionUpdateOpts} updateSpec
-   * @return {ExtensionUpdateResult}
+   * @return {Promise<ExtensionUpdateResult>}
    */
-  async update ({ext, unsafe}) {
+  async _update ({ext, unsafe}) {
     const shouldUpdateAll = ext === UPDATE_ALL;
     // if we're specifically requesting an update for an extension, make sure it's installed
     if (!shouldUpdateAll && !this.config.isInstalled(ext)) {
@@ -380,10 +366,12 @@ export default class ExtensionCommand {
     const extsToUpdate = shouldUpdateAll ? Object.keys(this.config.installedExtensions) : [ext];
 
     // 'errors' will have ext names as keys and error objects as values
+    /** @type {Record<string,Error>} */
     const errors = {};
 
     // 'updates' will have ext names as keys and update objects as values, where an update
     // object is of the form {from: versionString, to: versionString}
+    /** @type {Record<string,UpdateReport>} */
     const updates = {};
 
     for (const e of extsToUpdate) {
@@ -436,27 +424,20 @@ export default class ExtensionCommand {
     return {updates, errors};
   }
 
-  /**
-   * @typedef PossibleUpdates
-   * @property {string} current - current version
-   * @property {string|null} safeUpdate - version we can safely update to if it exists, or null
-   * @property {string|null} unsafeUpdate - version we can unsafely update to if it exists, or null
-   */
-
   /**
    * Given an extension name, figure out what its highest possible version upgrade is, and also the
    * highest possible safe upgrade.
    *
    * @param {string} ext - name of extension
-   * @return {PossibleUpdates}
+   * @return {Promise<PossibleUpdates>}
    */
   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 this.npm.getLatestVersion(pkgName);
-    let safeUpdate = await this.npm.getLatestSafeUpgradeVersion(pkgName, version);
+    let unsafeUpdate = await npm.getLatestVersion(this.config.appiumHome, pkgName);
+    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;
@@ -479,11 +460,225 @@ export default class ExtensionCommand {
    *
    * @param {string} ext - 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 this.installViaNpm({ext, pkgName, pkgVer: version});
-    this.config.installedExtensions[ext].version = version;
-    await this.config.write();
+    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);
+  }
+
+  /**
+   * Runs a script cached inside the "scripts" field under "appium"
+   * inside of the driver/plugins "package.json" file. Will throw
+   * an error if the driver/plugin does not contain a "scripts" field
+   * underneath the "appium" field in its package.json, if the
+   * "scripts" field is not a plain object, or if the scriptName is
+   * not found within "scripts" object.
+   *
+   * @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`);
+    }
+
+    const extConfig = this.config.installedExtensions[ext];
+
+    // 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`);
+    }
+
+    const extScripts = extConfig.scripts;
+
+    if (!_.isPlainObject(extScripts)) {
+      throw new Error(`The ${this.type} named '${ext}' "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}'`);
+    }
+
+    const runner = new SubProcess(process.execPath, [
+      extScripts[scriptName]
+    ], {
+      cwd: this.config.getInstallPath(ext)
+    });
+
+    const output = new RingBuffer(50);
+
+    runner.on('stream-line', (line) => {
+      output.enqueue(line);
+      log(this.isJsonOutput, line);
+    });
+
+    await runner.start(0);
+
+    try {
+      await runner.join();
+      log(this.isJsonOutput, `${scriptName} successfully ran`.green);
+      return {output: output.getBuff()};
+    } catch (err) {
+      log(this.isJsonOutput, `Encountered an error when running '${scriptName}': ${err.message}`.red);
+      return {error: err.message, output: output.getBuff()};
+    }
   }
 }
+
+export default ExtensionCommand;
+export {ExtensionCommand};
+
+/**
+ * Options for the {@linkcode ExtensionCommand} constructor
+ * @template {ExtensionType} ExtType
+ * @typedef ExtensionCommandOptions
+ * @property {ExtensionConfig<ExtType>} config - the `DriverConfig` or `PluginConfig` instance used for this command
+ * @property {boolean} json - whether the output of this command should be JSON or text
+ */
+
+/**
+ * Extra stuff about extensions; used indirectly by {@linkcode ExtensionCommand.list}.
+ *
+ * @typedef ExtensionMetadata
+ * @property {boolean} installed - If `true`, the extension is installed
+ * @property {string?} updateVersion - If the extension is installed, the version it can be updated to
+ * @property {string?} unsafeUpdateVersion - Same as above, but a major version bump
+ * @property {boolean} upToDate - If the extension is installed and the latest
+ */
+
+/**
+ * @typedef {import('../../types').ExtensionType} ExtensionType
+ * @typedef {import('../../types').DriverType} DriverType
+ * @typedef {import('../../types').PluginType} PluginType
+ */
+
+/**
+ * @template {ExtensionType} ExtType
+ * @typedef {import('../../types/appium-manifest').ExtRecord<ExtType>} ExtRecord
+ */
+
+/**
+ * @template {ExtensionType} ExtType
+ * @typedef {import('../extension/extension-config').ExtensionConfig<ExtType>} ExtensionConfig
+ */
+
+/**
+ * @template {ExtensionType} ExtType
+ * @typedef {import('../../types/external-manifest').ExtMetadata<ExtType>} ExtMetadata
+ */
+
+/**
+ * @template {ExtensionType} ExtType
+ * @typedef {import('../../types/appium-manifest').ExtManifest<ExtType>} ExtManifest
+ */
+
+/**
+ * @template {ExtensionType} ExtType
+ * @typedef {import('../../types/external-manifest').ExtPackageJson<ExtType>} ExtPackageJson
+ */
+
+/**
+ * Possible return value for {@linkcode ExtensionCommand.list}
+ * @typedef UninstalledExtensionListData
+ * @property {string} pkgName
+ * @property {false} installed
+ */
+
+/**
+ * Possible return value for {@linkcode ExtensionCommand.list}
+ * @typedef {import('../../types/appium-manifest').InternalMetadata & ExtensionMetadata} InstalledExtensionListData
+ */
+
+/**
+ * Return value of {@linkcode ExtensionCommand.list}.
+ * @typedef {Record<string,InstalledExtensionListData|UninstalledExtensionListData>} ExtensionListData
+ */
+
+/**
+ * Options for {@linkcode ExtensionCommand._run}.
+ * @typedef RunOptions
+ * @property {string} ext - name of the extension to run a script from
+ * @property {string} scriptName - name of the script to run
+ */
+
+/**
+ * Return value of {@linkcode ExtensionCommand._run}
+ *
+ * @typedef RunOutput
+ * @property {string} [error] - error message if script ran unsuccessfully, otherwise undefined
+ * @property {string[]} output - script output
+ */
+
+/**
+ * Options for {@linkcode ExtensionCommand._update}.
+ * @typedef ExtensionUpdateOpts
+ * @property {string} ext - the name of the extension to update
+ * @property {boolean} unsafe - if true, will perform unsafe updates past major revision boundaries
+ */
+
+/**
+ * Return value of {@linkcode ExtensionCommand._update}.
+ * @typedef ExtensionUpdateResult
+ * @property {Record<string,Error>} errors - map of ext names to error objects
+ * @property {Record<string,UpdateReport>} updates - map of ext names to {@linkcode UpdateReport}s
+ */
+
+/**
+ * Part of result of {@linkcode ExtensionCommand._update}.
+ * @typedef UpdateReport
+ * @property {string} from - version the extension was updated from
+ * @property {string} to - version the extension was updated to
+ */
+
+/**
+ * Options for {@linkcode ExtensionCommand._uninstall}.
+ * @typedef UninstallOpts
+ * @property {string} ext - the name or spec of an extension to uninstall
+ */
+
+/**
+ * Used by {@linkcode ExtensionCommand.getPostInstallText}
+ * @typedef ExtensionArgs
+ * @property {string} extName - the name of an extension
+ * @property {object} extData - the data for an installed extension
+ */
+
+/**
+ * Options for {@linkcode ExtensionCommand.installViaNpm}
+ * @typedef InstallViaNpmArgs
+ * @property {string} ext - 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
+ */
+
+/**
+ * Object returned by {@linkcode ExtensionCommand.checkForExtensionUpdate}
+ * @typedef PossibleUpdates
+ * @property {string} current - current version
+ * @property {string?} safeUpdate - version we can safely update to if it exists, or null
+ * @property {string?} unsafeUpdate - version we can unsafely update to if it exists, or null
+ */
+
+/**
+ * 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} [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
+ */
+
+/**
+ * @template {ExtensionType} ExtType
+ * @typedef {ExtType extends DriverType ? typeof import('../constants').KNOWN_DRIVERS : ExtType extends PluginType ? typeof import('../constants').KNOWN_PLUGINS : never} KnownExtensions
+ */