appium 2.0.0-beta.45 → 2.0.0-beta.47

package/lib/cli/extension-command.js

@@ -18,6 +18,16 @@ const UPDATE_ALL = 'installed';
 class NotUpdatableError extends Error {}
 class NoUpdatesAvailableError extends Error {}
 
+/**
+ * Omits `driverName`/`pluginName` props from the receipt to make a {@linkcode ExtManifest}
+ * @template {ExtensionType} ExtType
+ * @param {ExtInstallReceipt<ExtType>} receipt
+ * @returns {ExtManifest<ExtType>}
+ */
+function receiptToManifest(receipt) {
+  return /** @type {ExtManifest<ExtType>} */ (_.omit(receipt, 'driverName', 'pluginName'));
+}
+
 /**
  * @template {ExtensionType} ExtType
  */
@@ -128,10 +138,14 @@ class ExtensionCommand {
           // also don't need to check for updates on non-npm exts
           continue;
         }
-        const updates = await this.checkForExtensionUpdate(ext);
-        data.updateVersion = updates.safeUpdate;
-        data.unsafeUpdateVersion = updates.unsafeUpdate;
-        data.upToDate = updates.safeUpdate === null && updates.unsafeUpdate === null;
+        try {
+          const updates = await this.checkForExtensionUpdate(ext);
+          data.updateVersion = updates.safeUpdate;
+          data.unsafeUpdateVersion = updates.unsafeUpdate;
+          data.upToDate = updates.safeUpdate === null && updates.unsafeUpdate === null;
+        } catch (e) {
+          data.updateError = e.message;
+        }
       }
     });
 
@@ -149,8 +163,15 @@ class ExtensionCommand {
       let upToDateTxt = '';
       let unsafeUpdateTxt = '';
       if (data.installed) {
-        const {installType, installSpec, updateVersion, unsafeUpdateVersion, version, upToDate} =
-          data;
+        const {
+          installType,
+          installSpec,
+          updateVersion,
+          unsafeUpdateVersion,
+          version,
+          upToDate,
+          updateError,
+        } = data;
         let typeTxt;
         switch (installType) {
           case INSTALL_TYPE_GIT:
@@ -166,14 +187,18 @@ class ExtensionCommand {
         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;
+          if (updateError) {
+            updateTxt = ` [Cannot check for updates: ${updateError}]`.red;
+          } else {
+            if (updateVersion) {
+              updateTxt = ` [${updateVersion} available]`.magenta;
+            }
+            if (upToDate) {
+              upToDateTxt = ` [Up to date]`.green;
+            }
+            if (unsafeUpdateVersion) {
+              unsafeUpdateTxt = ` [${unsafeUpdateVersion} available (potentially unsafe)]`.cyan;
+            }
           }
         }
       }
@@ -187,12 +212,12 @@ class ExtensionCommand {
   /**
    * Install an extension
    *
-   * @param {InstallArgs} args
+   * @param {InstallOpts} opts
    * @return {Promise<ExtRecord<ExtType>>} map of all installed extension names to extension data
    */
   async _install({installSpec, installType, packageName}) {
-    /** @type {ExtensionFields<ExtType>} */
-    let extData;
+    /** @type {ExtInstallReceipt<ExtType>} */
+    let receipt;
 
     if (packageName && [INSTALL_TYPE_LOCAL, INSTALL_TYPE_NPM].includes(installType)) {
       throw this._createFatalError(`When using --source=${installType}, cannot also use --package`);
@@ -205,7 +230,7 @@ class ExtensionCommand {
     /**
      * @type {InstallViaNpmArgs}
      */
-    let installOpts;
+    let installViaNpmOpts;
 
     /**
      * The probable (?) name of the extension derived from the install spec.
@@ -223,8 +248,9 @@ class ExtensionCommand {
             'it should be of the form <org>/<repo>'
         );
       }
-      installOpts = {
+      installViaNpmOpts = {
         installSpec,
+        installType,
         pkgName: /** @type {string} */ (packageName),
       };
       probableExtName = installSpec;
@@ -232,8 +258,9 @@ class ExtensionCommand {
       // 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$/, '');
-      installOpts = {
+      installViaNpmOpts = {
         installSpec,
+        installType,
         pkgName: /** @type {string} */ (packageName),
       };
       probableExtName = installSpec;
@@ -279,7 +306,7 @@ class ExtensionCommand {
           installType = INSTALL_TYPE_NPM;
         }
       }
-      installOpts = {installSpec, pkgName, pkgVer};
+      installViaNpmOpts = {installSpec, pkgName, pkgVer, installType};
     }
 
     // fail fast here if we can
@@ -291,11 +318,11 @@ class ExtensionCommand {
       );
     }
 
-    extData = await this.installViaNpm(installOpts);
+    receipt = await this.installViaNpm(installViaNpmOpts);
 
     // 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`)];
+    const extName = receipt[/** @type {string} */ (`${this.type}Name`)];
 
     // check _a second time_ with the more-accurate extName
     if (this.config.isInstalled(extName)) {
@@ -308,10 +335,9 @@ class ExtensionCommand {
 
     // 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 extManifest = receiptToManifest(receipt);
+
     const [errors, warnings] = await B.all([
       this.config.getProblems(extName, extManifest),
       this.config.getWarnings(extName, extManifest),
@@ -340,7 +366,7 @@ class ExtensionCommand {
     }
 
     // log info for the user
-    this.log.info(this.getPostInstallText({extName, extData}));
+    this.log.info(this.getPostInstallText({extName, extData: receipt}));
 
     return this.config.installedExtensions;
   }
@@ -349,21 +375,28 @@ class ExtensionCommand {
    * Install an extension via NPM
    *
    * @param {InstallViaNpmArgs} args
+   * @returns {Promise<ExtInstallReceipt<ExtType>>}
    */
-  async installViaNpm({installSpec, pkgName, pkgVer}) {
+  async installViaNpm({installSpec, pkgName, pkgVer, installType}) {
     const npmSpec = `${pkgName}${pkgVer ? '@' + pkgVer : ''}`;
     const specMsg = npmSpec === installSpec ? '' : ` using NPM install spec '${npmSpec}'`;
     const msg = `Installing '${installSpec}'${specMsg}`;
     try {
-      const pkgJsonData = await spinWith(this.isJsonOutput, msg, async () => {
-        const pkgJsonData = await npm.installPackage(this.config.appiumHome, pkgName, {
+      const {pkg, path} = await spinWith(this.isJsonOutput, msg, async () => {
+        const {pkg, installPath: path} = await npm.installPackage(this.config.appiumHome, pkgName, {
           pkgVer,
+          installType,
         });
-        this.validatePackageJson(pkgJsonData, installSpec);
-        return pkgJsonData;
+        this.validatePackageJson(pkg, installSpec);
+        return {pkg, path};
       });
 
-      return this.getExtensionFields(pkgJsonData);
+      return this.getInstallationReceipt({
+        pkg,
+        installPath: path,
+        installType,
+        installSpec,
+      });
     } catch (err) {
       throw this._createFatalError(`Encountered an error when installing package: ${err.message}`);
     }
@@ -382,25 +415,31 @@ class ExtensionCommand {
   }
 
   /**
-   * Take an NPM module's package.json and extract Appium driver information from a special
-   * 'appium' field in the JSON data. We need this information to e.g. determine which class to
-   * load as the main driver class, or to be able to detect incompatibilities between driver and
-   * appium versions.
+   * Once a package is installed on-disk, this gathers some necessary metadata for validation.
    *
-   * @param {ExtPackageJson<ExtType>} pkgJson - the package.json data for a driver module, as if it had been straightforwardly 'require'd
-   * @returns {ExtensionFields<ExtType>}
+   * @param {GetInstallationReceiptOpts<ExtType>} opts
+   * @returns {ExtInstallReceipt<ExtType>}
    */
-  getExtensionFields(pkgJson) {
-    const {appium, name, version, peerDependencies} = pkgJson;
+  getInstallationReceipt({pkg, installPath, installType, installSpec}) {
+    const {appium, name, version, peerDependencies} = pkg;
 
-    /** @type {unknown} */
-    const result = {
-      ...appium,
+    /** @type {import('appium/types').InternalMetadata} */
+    const internal = {
       pkgName: name,
       version,
+      installType,
+      installSpec,
+      installPath,
       appiumVersion: peerDependencies?.appium,
     };
-    return /** @type {ExtensionFields<ExtType>} */ (result);
+
+    /** @type {ExtMetadata<ExtType>} */
+    const extMetadata = appium;
+
+    return {
+      ...internal,
+      ...extMetadata,
+    };
   }
 
   /**
@@ -410,13 +449,13 @@ class ExtensionCommand {
    * - `name`
    * - `version`
    * - `appium`
-   * @param {import('type-fest').PackageJson} pkgJson - `package.json` of extension
+   * @param {import('type-fest').PackageJson} pkg - `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>}
+   * @returns {pkg is ExtPackageJson<ExtType>}
    */
-  validatePackageJson(pkgJson, installSpec) {
-    const {appium, name, version} = /** @type {ExtPackageJson<ExtType>} */ (pkgJson);
+  validatePackageJson(pkg, installSpec) {
+    const {appium, name, version} = /** @type {ExtPackageJson<ExtType>} */ (pkg);
 
     /**
      *
@@ -608,9 +647,10 @@ class ExtensionCommand {
    * @returns {Promise<void>}
    */
   async updateExtension(installSpec, version) {
-    const {pkgName} = this.config.installedExtensions[installSpec];
+    const {pkgName, installType} = this.config.installedExtensions[installSpec];
     const extData = await this.installViaNpm({
       installSpec,
+      installType,
       pkgName,
       pkgVer: version,
     });
@@ -637,7 +677,7 @@ class ExtensionCommand {
     const extConfig = this.config.installedExtensions[installSpec];
 
     // note: TS cannot understand that _.has() is a type guard
-    if (!extConfig.scripts) {
+    if (!('scripts' in extConfig)) {
       throw this._createFatalError(
         `The ${this.type} named '${installSpec}' does not contain the ` +
           `"scripts" field underneath the "appium" field in its package.json`
@@ -646,13 +686,13 @@ class ExtensionCommand {
 
     const extScripts = extConfig.scripts;
 
-    if (!_.isPlainObject(extScripts)) {
+    if (!extScripts || !_.isPlainObject(extScripts)) {
       throw this._createFatalError(
         `The ${this.type} named '${installSpec}' "scripts" field must be a plain object`
       );
     }
 
-    if (!_.has(extScripts, scriptName)) {
+    if (!(scriptName in extScripts)) {
       throw this._createFatalError(
         `The ${this.type} named '${installSpec}' does not support the script: '${scriptName}'`
       );
@@ -701,6 +741,7 @@ export {ExtensionCommand};
  * @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
+ * @property {string?} updateError - Update check error message (if present)
  */
 
 /**
@@ -734,6 +775,11 @@ export {ExtensionCommand};
  * @typedef {import('appium/types').ExtPackageJson<ExtType>} ExtPackageJson
  */
 
+/**
+ * @template {ExtensionType} ExtType
+ * @typedef {import('appium/types').ExtInstallReceipt<ExtType>} ExtInstallReceipt
+ */
+
 /**
  * Possible return value for {@linkcode ExtensionCommand.list}
  * @typedef UninstalledExtensionListData
@@ -806,6 +852,7 @@ export {ExtensionCommand};
  * @typedef InstallViaNpmArgs
  * @property {string} installSpec - the name or spec of an extension to install
  * @property {string} pkgName - the NPM package name of the extension
+ * @property {import('appium/types').InstallType} installType - type of install
  * @property {string} [pkgVer] - the specific version of the NPM package
  */
 
@@ -819,18 +866,12 @@ export {ExtensionCommand};
 
 /**
  * Options for {@linkcode ExtensionCommand._install}
- * @typedef InstallArgs
+ * @typedef InstallOpts
  * @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 {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, 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
@@ -841,3 +882,17 @@ export {ExtensionCommand};
  * @property {boolean} showInstalled - whether should show only installed extensions
  * @property {boolean} showUpdates - whether should show available updates
  */
+
+/**
+ * Opts for {@linkcode ExtensionCommand.getInstallationReceipt}
+ * @template {ExtensionType} ExtType
+ * @typedef GetInstallationReceiptOpts
+ * @property {string} installPath
+ * @property {string} installSpec
+ * @property {ExtPackageJson<ExtType>} pkg
+ * @property {InstallType} installType
+ */
+
+/**
+ * @typedef {import('appium/types').InstallType} InstallType
+ */

package/lib/cli/extension.js

@@ -1,7 +1,8 @@
 /* eslint-disable no-console */
+import {DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
+import {isExtensionCommandArgs} from '../utils';
 import DriverCommand from './driver-command';
 import PluginCommand from './plugin-command';
-import {DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
 import {errAndQuit, JSON_SPACES} from './utils';
 
 export const commandClasses = Object.freeze(
@@ -15,18 +16,18 @@ export const commandClasses = Object.freeze(
  * Run a subcommand of the 'appium driver' type. Each subcommand has its own set of arguments which
  * can be represented as a JS object.
  *
- * @param {import('appium/types').Args<import('appium/types').WithExtSubcommand>} args - JS object where the key is the parameter name (as defined in
+ * @template {import('appium/types').CliExtensionCommand} Cmd
+ * @template {import('appium/types').CliExtensionSubcommand} SubCmd
+ * @param {import('appium/types').Args<Cmd, SubCmd>} args - JS object where the key is the parameter name (as defined in
  * driver-parser.js)
- * @template {ExtensionType} ExtType
- * @param {import('../extension/extension-config').ExtensionConfig<ExtType>} config - Extension config object
+ * @param {import('../extension/extension-config').ExtensionConfig<Cmd>} config - Extension config object
  */
 async function runExtensionCommand(args, config) {
   // TODO driver config file should be locked while any of these commands are
   // running to prevent weird situations
   let jsonResult = null;
-  const {extensionType: type} = config;
-  const extCmd = args[`${type}Command`];
-  if (!extCmd) {
+  const {extensionType: type} = config; // NOTE this is the same as `args.subcommand`
+  if (!isExtensionCommandArgs(args)) {
     throw new TypeError(`Cannot call ${type} command without a subcommand like 'install'`);
   }
   let {json, suppressOutput} = args;
@@ -34,7 +35,7 @@ async function runExtensionCommand(args, config) {
   if (suppressOutput) {
     json = true;
   }
-  const CommandClass = /** @type {ExtCommand<ExtType>} */ (commandClasses[type]);
+  const CommandClass = /** @type {ExtCommand<Cmd>} */ (commandClasses[type]);
   const cmd = new CommandClass({config, json});
   try {
     jsonResult = await cmd.execute(args);

package/lib/cli/parser.js

@@ -89,9 +89,9 @@ class ArgParser {
    * If no subcommand is passed in, this method will inject the `server` subcommand.
    *
    * `ArgParser.prototype.parse_args` is an alias of this method.
-   * @template [T=import('appium/types').WithServerSubcommand]
+   * @template {import('appium/types').CliCommand} [Cmd=import('appium/types').ServerCommand]
    * @param {string[]} [args] - Array of arguments, ostensibly from `process.argv`. Gathers args from `process.argv` if not provided.
-   * @returns {import('appium/types').Args<T>} - The parsed arguments
+   * @returns {import('appium/types').Args<Cmd>} - The parsed arguments
    */
   parseArgs(args = process.argv.slice(2)) {
     if (!NON_SERVER_ARGS.has(args[0])) {

package/lib/config-file.js

@@ -154,9 +154,8 @@ export function normalizeConfig(config) {
   const normalize = (config, section) => {
     const obj = _.isUndefined(section) ? config : _.get(config, section, config);
 
-    const mappedObj = _.mapKeys(
-      obj,
-      (__, prop) => schema.properties[prop]?.appiumCliDest ?? _.camelCase(prop)
+    const mappedObj = _.mapKeys(obj, (__, prop) =>
+      _.get(schema, `properties.server.properties[${prop}].appiumCliDest`, _.camelCase(prop))
     );
 
     return _.mapValues(mappedObj, (value, property) => {

package/lib/config.js

@@ -298,11 +298,12 @@ function showConfig(nonDefaultPreConfigParsedArgs, configResult, defaults, parse
   } else {
     console.log(`\n(no configuration file loaded)`);
   }
-  if (_.isEmpty(nonDefaultPreConfigParsedArgs)) {
+  const compactedNonDefaultPreConfigArgs = compactConfig(nonDefaultPreConfigParsedArgs);
+  if (_.isEmpty(compactedNonDefaultPreConfigArgs)) {
     console.log(`\n(no CLI parameters provided)`);
   } else {
     console.log('\nvia CLI or function call:\n');
-    console.dir(compactConfig(nonDefaultPreConfigParsedArgs));
+    console.dir(compactedNonDefaultPreConfigArgs);
   }
   console.log('\nfinal configuration:\n');
   console.dir(compactConfig(parsedArgs));

package/lib/constants.js

@@ -29,6 +29,7 @@ export const KNOWN_PLUGINS = Object.freeze(
     images: '@appium/images-plugin',
     'execute-driver': '@appium/execute-driver-plugin',
     'relaxed-caps': '@appium/relaxed-caps-plugin',
+    'universal-xml': '@appium/universal-xml-plugin',
   })
 );
 
@@ -40,13 +41,8 @@ export const KNOWN_DRIVERS = Object.freeze(
   /** @type {const} */ ({
     uiautomator2: 'appium-uiautomator2-driver',
     xcuitest: 'appium-xcuitest-driver',
-    youiengine: 'appium-youiengine-driver',
-    windows: 'appium-windows-driver',
-    mac: 'appium-mac-driver',
     mac2: 'appium-mac2-driver',
     espresso: 'appium-espresso-driver',
-    tizen: 'appium-tizen-driver',
-    flutter: 'appium-flutter-driver',
     safari: 'appium-safari-driver',
     gecko: 'appium-geckodriver',
   })
@@ -67,3 +63,8 @@ export const EXT_SUBCOMMAND_INSTALL = 'install';
 export const EXT_SUBCOMMAND_UNINSTALL = 'uninstall';
 export const EXT_SUBCOMMAND_UPDATE = 'update';
 export const EXT_SUBCOMMAND_RUN = 'run';
+
+/**
+ * Current revision of the manifest (`extensions.yaml`) schema
+ */
+export const CURRENT_SCHEMA_REV = 3;

package/lib/extension/extension-config.js

@@ -441,7 +441,7 @@ export class ExtensionConfig {
 
   /**
    * @param {ExtName<ExtType>} extName
-   * @param {ExtManifest<ExtType>|import('../cli/extension-command').ExtensionFields<ExtType>} extManifest
+   * @param {ExtManifest<ExtType>} extManifest
    * @param {ExtensionConfigMutationOpts} [opts]
    * @returns {Promise<void>}
    */
@@ -504,11 +504,17 @@ export class ExtensionConfig {
   }
 
   /**
-   * @param {string} extName
+   * Returns--with reasonable accuracy--the path on disk to the extension.
+   *
+   * If `installPath` is present in the manifest, then it is used; otherwise we just guess.
+   * @param {keyof typeof this.installedExtensions} extName
    * @returns {string}
    */
   getInstallPath(extName) {
-    return path.join(this.appiumHome, 'node_modules', this.installedExtensions[extName].pkgName);
+    return (
+      this.installedExtensions[extName]?.installPath ??
+      path.join(this.appiumHome, 'node_modules', this.installedExtensions[extName].pkgName)
+    );
   }
 
   /**
@@ -628,36 +634,39 @@ export {INSTALL_TYPE_NPM, INSTALL_TYPE_GIT, INSTALL_TYPE_LOCAL, INSTALL_TYPE_GIT
 /**
  * @typedef {import('@appium/types').ExtensionType} ExtensionType
  * @typedef {import('./manifest').Manifest} Manifest
+ * @typedef {import('../cli/extension-command').ExtensionListData} ExtensionListData
+ * @typedef {import('../cli/extension-command').InstalledExtensionListData} InstalledExtensionListData
+ * @typedef {import('appium/types').InstallType} InstallType
  */
 
 /**
- * @template T
- * @typedef {import('appium/types').ExtManifest<T>} ExtManifest
+ * @template {ExtensionType} ExtType
+ * @typedef {import('appium/types').ExtManifest<ExtType>} ExtManifest
  */
 
 /**
- * @template T
- * @typedef {import('appium/types').ExtManifestWithSchema<T>} ExtManifestWithSchema
+ * @template {ExtensionType} ExtType
+ * @typedef {ExtManifest<ExtType> & {schema: NonNullable<ExtManifest<ExtType>['schema']>}} ExtManifestWithSchema
  */
 
 /**
- * @template T
- * @typedef {import('appium/types').ExtName<T>} ExtName
+ * @template {ExtensionType} ExtType
+ * @typedef {import('appium/types').ExtName<ExtType>} ExtName
  */
 
 /**
- * @template T
- * @typedef {import('appium/types').ExtClass<T>} ExtClass
+ * @template {ExtensionType} ExtType
+ * @typedef {import('appium/types').ExtClass<ExtType>} ExtClass
  */
 
 /**
- * @template T
- * @typedef {import('appium/types').ExtRecord<T>} ExtRecord
+ * @template {ExtensionType} ExtType
+ * @typedef {import('appium/types').ExtRecord<ExtType>} ExtRecord
  */
 
 /**
- * @template T
- * @typedef {import('../cli/extension').ExtCommand<T>} ExtCommand
+ * @template {ExtensionType} ExtType
+ * @typedef {import('../cli/extension').ExtCommand<ExtType>} ExtCommand
  */
 
 /**
@@ -665,13 +674,3 @@ export {INSTALL_TYPE_NPM, INSTALL_TYPE_GIT, INSTALL_TYPE_LOCAL, INSTALL_TYPE_GIT
  * @typedef ExtensionConfigMutationOpts
  * @property {boolean} [write=true] Whether or not to write the manifest to disk after a mutation operation
  */
-
-/**
- * A valid install type
- * @typedef {typeof INSTALL_TYPE_NPM | typeof INSTALL_TYPE_GIT | typeof INSTALL_TYPE_LOCAL | typeof INSTALL_TYPE_GITHUB} InstallType
- */
-
-/**
- * @typedef {import('../cli/extension-command').ExtensionListData} ExtensionListData
- * @typedef {import('../cli/extension-command').InstalledExtensionListData} InstalledExtensionListData
- */

package/lib/extension/manifest-migrations.js

@@ -0,0 +1,99 @@
+import log from '../logger';
+
+/**
+ * This contains logic to migrate old versions of `extensions.yaml` to new versions.
+ *
+ * @module
+ */
+
+/**
+ * Constant for v3 of the schema rev.
+ */
+const SCHEMA_REV_3 = 3;
+
+/**
+ * Collection of functions to migrate from one version to another
+ * @type {{[P in keyof ManifestDataVersions]?: Migration}}
+ */
+const Migrations = {
+  /**
+   * If `installPath` is missing from the `ExtManifest` for any extension, return `true`.
+   *
+   * We cannot easily determine the path of any given extension here, but returning `true`
+   * will cause the `Manifest` to sync with the filesystem, which will populate the missing field.
+   *
+   * @type {Migration}
+   */
+  [SCHEMA_REV_3]: (data) => {
+    let shouldSync = false;
+    const allExtData = [...Object.values(data.drivers), ...Object.values(data.plugins)];
+    for (const metadata of allExtData) {
+      if (!('installPath' in metadata)) {
+        shouldSync = true;
+        break;
+      }
+    }
+    return shouldSync;
+  },
+};
+
+/**
+ * Set `schemaRev` to a specific version
+ * @param {AnyManifestDataVersion} data
+ * @param {keyof ManifestDataVersions} version
+ * @returns {boolean} Whether the data was modified
+ */
+function setSchemaRev(data, version) {
+  if (data.schemaRev ?? 0 < version) {
+    data.schemaRev = version;
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Applies a series of migration functions to a manifest to update its manifest schema version.
+ *
+ * `data` is modified in-place.
+ *
+ * @param {Manifest} manifest
+ * @param {AnyManifestDataVersion} data
+ * @returns {Promise<boolean>} If `true` existing packages should be synced from disk and the manifest should be persisted.
+ */
+export async function migrate(manifest, data) {
+  let didChange = false;
+  for await (const [v, migration] of Object.entries(Migrations)) {
+    const version = /** @type {keyof ManifestDataVersions} */ (Number(v));
+    didChange = (await migration(data, manifest)) || didChange;
+    didChange = setSchemaRev(data, version) || didChange;
+  }
+
+  if (didChange) {
+    // this is not _technically_ true, since we don't actually write the file here.
+    log.info(`Upgraded extension manifest to schema v${data.schemaRev}`);
+  }
+  return didChange;
+}
+
+/**
+ * Migration functions take a {@linkcode Manifest} and its data and **mutates `data` in-place**.
+ *
+ * A migration function should not modify `schemaRev`, as this is done automatically.
+ *
+ * A migration function can also call out to, say, {@linkcode Manifest.syncWithInstalledExtensions}, which
+ * may apply the mutation itself.
+ *
+ * Note that at the time of writing, we're not able to determine the version of the _current_ manifest file if there is no `schemaRev` prop present (and we may not want to trust it anyway).
+ * @callback Migration
+ * @param {AnyManifestDataVersion} data - The raw data from `Manifest`
+ * @param {Manifest} manifest - The `Manifest` instance
+ * @returns {boolean|Promise<boolean>} If `true`, then something changed
+ */
+
+/**
+ * @typedef {import('appium/types').ManifestData} ManifestData
+ * @typedef {import('appium/types').AnyManifestDataVersion} AnyManifestDataVersion
+ * @typedef {import('appium/types').ManifestDataVersions} ManifestDataVersions
+ * @typedef {import('appium/types').ManifestV2.ManifestData} ManifestDataV2
+ * @typedef {import('./manifest').Manifest} Manifest
+ */