appium 3.2.2 → 3.3.1

package/lib/extension/{extension-config.js → extension-config.ts}

@@ -1,18 +1,28 @@
+import type {ExtensionType} from '@appium/types';
+import type {ExtClass, ExtManifest, ExtName, ExtRecord, InstallType} from 'appium/types';
+import type {SchemaObject} from 'ajv';
 import {util, fs, system} from '@appium/support';
 import B from 'bluebird';
 import _ from 'lodash';
 import path from 'node:path';
+import {pathToFileURL} from 'node:url';
 import resolveFrom from 'resolve-from';
 import {satisfies} from 'semver';
 import {commandClasses} from '../cli/extension';
-import {APPIUM_VER} from '../config';
-import log from '../logger';
+import type {
+  ExtensionList,
+  ExtensionListData,
+  InstalledExtensionListData,
+} from '../cli/extension-command';
+import type {ExtCommand} from '../cli/extension';
+import {APPIUM_VER} from '../helpers/build';
+import {log} from '../logger';
 import {
   ALLOWED_SCHEMA_EXTENSIONS,
   isAllowedSchemaFileExtension,
   registerSchema,
 } from '../schema/schema';
-import { pathToFileURL } from 'node:url';
+import type {Manifest} from './manifest';
 
 const DEFAULT_ENTRY_POINT = 'index.js';
 /**
@@ -43,8 +53,7 @@ export const INSTALL_TYPE_GIT = 'git';
  */
 export const INSTALL_TYPE_DEV = 'dev';
 
-/** @type {Set<InstallType>} */
-export const INSTALL_TYPES = new Set([
+export const INSTALL_TYPES = new Set<InstallType>([
   INSTALL_TYPE_GIT,
   INSTALL_TYPE_GITHUB,
   INSTALL_TYPE_LOCAL,
@@ -52,80 +61,98 @@ export const INSTALL_TYPES = new Set([
   INSTALL_TYPE_DEV,
 ]);
 
-/**
- * This class is abstract. It should not be instantiated directly.
- *
- * Subclasses should provide the generic parameter to implement.
- * @template {ExtensionType} ExtType
- */
-export class ExtensionConfig {
-  /**
-   * The type of extension this class is responsible for.
-   * @type {ExtType}
-   */
-  extensionType;
-
-  /**
-   * Manifest data for the extensions of this type.
-   *
-   * This data should _not_ be written to by anything but {@linkcode Manifest}.
-   * @type {Readonly<ExtRecord<ExtType>>}
-   */
-  installedExtensions;
+export type ExtManifestProblem = {err: string; val: unknown};
 
-  /** @type {import('@appium/types').AppiumLogger} */
-  log;
+export type ExtManifestWithSchema<E extends ExtensionType> = ExtManifest<E> & {
+  schema: NonNullable<ExtManifest<E>['schema']>;
+};
 
-  /** @type {Manifest} */
-  manifest;
+export type ExtensionConfigMutationOpts = {write?: boolean};
 
-  /**
-   * @type {import('../cli/extension-command').ExtensionList<ExtType>|undefined}
-   */
-  #listDataCache;
+/**
+ * Shared configuration and validation for installed Appium extensions (drivers or plugins).
+ * Subclasses fix the extension kind; do not instantiate this class directly.
+ */
+export abstract class ExtensionConfig<ExtType extends ExtensionType> {
+  readonly extensionType: ExtType;
+  readonly manifest: Manifest;
+  installedExtensions: ExtRecord<ExtType>;
+  #listDataCache: ExtensionList<ExtType> | undefined;
 
-  /**
-   * @protected
-   * @param {ExtType} extensionType - Type of extension
-   * @param {Manifest} manifest - `Manifest` instance
-   */
-  constructor(extensionType, manifest) {
+  protected constructor(extensionType: ExtType, manifest: Manifest) {
     this.extensionType = extensionType;
-    this.installedExtensions = manifest.getExtensionData(extensionType);
     this.manifest = manifest;
+    this.installedExtensions = manifest.getExtensionData(extensionType);
   }
 
-  get manifestPath() {
+  /** Path to `extensions.yaml` after the manifest has been read; otherwise undefined. */
+  get manifestPath(): string | undefined {
     return this.manifest.manifestPath;
   }
 
-  get appiumHome() {
+  /** `APPIUM_HOME` directory this config is tied to. */
+  get appiumHome(): string {
     return this.manifest.appiumHome;
   }
 
   /**
-   * Returns a list of errors for a given extension.
+   * Type guard: manifest entry includes a `schema` path or inline schema object.
+   *
+   * @param extManifest - Parsed extension metadata
+   */
+  static extDataHasSchema<E extends ExtensionType>(
+    extManifest: ExtManifest<E>
+  ): extManifest is ExtManifestWithSchema<E> {
+    return _.isString(extManifest?.schema) || _.isObject(extManifest?.schema);
+  }
+
+  private static async _readExtensionSchema<E extends ExtensionType>(
+    appiumHome: string,
+    extType: E,
+    extName: string,
+    extManifest: ExtManifestWithSchema<E>
+  ): Promise<SchemaObject | undefined> {
+    const {pkgName, schema: argSchemaPath} = extManifest;
+    if (!argSchemaPath) {
+      throw new TypeError(
+        `No \`schema\` property found in config for ${extType} ${pkgName} -- why is this function being called?`
+      );
+    }
+    let moduleObject: any;
+    if (_.isString(argSchemaPath)) {
+      const schemaPath = resolveFrom(appiumHome, path.join(pkgName, argSchemaPath));
+      moduleObject = require(schemaPath);
+    } else {
+      moduleObject = argSchemaPath;
+    }
+    // this sucks. default exports should be destroyed
+    const schema = moduleObject.__esModule ? moduleObject.default : moduleObject;
+    await registerSchema(extType, extName, schema as SchemaObject);
+    return schema;
+  }
+
+  /**
+   * Collects blocking validation issues for one extension (generic fields, type-specific rules, and schema).
    *
-   * @param {ExtName<ExtType>} extName
-   * @param {ExtManifest<ExtType>} extManifest
-   * @returns {ExtManifestProblem[]}
+   * @param extName - Extension key as stored in the manifest
+   * @param extManifest - Manifest entry for that extension
    */
-  getProblems(extName, extManifest) {
+  async getProblems(extName: string, extManifest: ExtManifest<ExtType>): Promise<ExtManifestProblem[]> {
     return [
       ...this.getGenericConfigProblems(extManifest, extName),
       ...this.getConfigProblems(extManifest, extName),
-      ...this.getSchemaProblems(extManifest, extName),
+      ...(await this.getSchemaProblems(extManifest, extName)),
     ];
   }
 
   /**
-   * Returns a list of warnings for a given extension.
+   * Collects non-fatal issues for one extension (e.g. manifest quirks, peer dependency mismatches).
+   * Warnings do not by themselves prevent loading.
    *
-   * @param {ExtName<ExtType>} extName
-   * @param {ExtManifest<ExtType>} extManifest
-   * @returns {Promise<string[]>}
+   * @param extName - Extension key as stored in the manifest
+   * @param extManifest - Manifest entry for that extension
    */
-  async getWarnings(extName, extManifest) {
+  async getWarnings(extName: string, extManifest: ExtManifest<ExtType>): Promise<string[]> {
     const [genericConfigWarnings, configWarnings] = await B.all([
       this.getGenericConfigWarnings(extManifest, extName),
       this.getConfigWarnings(extManifest, extName),
@@ -135,28 +162,16 @@ export class ExtensionConfig {
   }
 
   /**
-   * Returns a list of extension-type-specific issues. To be implemented by subclasses.
-   * @abstract
-   * @param {ExtManifest<ExtType>} extManifest
-   * @param {ExtName<ExtType>} extName
-   * @returns {Promise<string[]>}
-   */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  async getConfigWarnings(extManifest, extName) {
-    return [];
-  }
-
-  /**
+   * Turns per-extension errors and warnings into human-readable log lines for console output.
    *
-   * @param {Map<ExtName<ExtType>,ExtManifestProblem[]>} [errorMap]
-   * @param {Map<ExtName<ExtType>,string[]>} [warningMap]
+   * @param errorMap - Extension name to list of blocking problems
+   * @param warningMap - Extension name to list of warning strings
    */
-  getValidationResultSummaries(errorMap = new Map(), warningMap = new Map()) {
-    /**
-     * Array of computed strings
-     * @type {string[]}
-     */
-    const errorSummaries = [];
+  getValidationResultSummaries(
+    errorMap: Map<string, ExtManifestProblem[]> = new Map(),
+    warningMap: Map<string, string[]> = new Map()
+  ): {errorSummaries: string[]; warningSummaries: string[]} {
+    const errorSummaries: string[] = [];
     for (const [extName, problems] of errorMap.entries()) {
       if (_.isEmpty(problems)) {
         continue;
@@ -174,8 +189,7 @@ export class ExtensionConfig {
         );
       }
     }
-    /** @type {string[]} */
-    const warningSummaries = [];
+    const warningSummaries: string[] = [];
     for (const [extName, warnings] of warningMap.entries()) {
       if (_.isEmpty(warnings)) {
         continue;
@@ -192,27 +206,157 @@ export class ExtensionConfig {
   }
 
   /**
-   * Checks extensions for problems.  To be called by subclasses' `validate` method.
+   * Records a new installed extension in the manifest and optionally persists immediately.
    *
-   * Errors and warnings will be displayed to the user.
+   * @param extName - Manifest key for the extension
+   * @param extManifest - Full manifest payload
    *
-   * This method mutates `exts`.
+   * Pass `{ write: false }` to defer flushing until a later manifest write.
+   */
+  async addExtension(
+    extName: string,
+    extManifest: ExtManifest<ExtType>,
+    {write = true}: ExtensionConfigMutationOpts = {}
+  ): Promise<void> {
+    this.manifest.setExtension(this.extensionType, extName, extManifest);
+    if (write) {
+      await this.manifest.write();
+    }
+  }
+
+  /**
+   * Merges new metadata into an existing extension entry and optionally writes the manifest.
    *
-   * @protected
-   * @param {ExtRecord<ExtType>} exts - Lookup of extension names to {@linkcode ExtManifest} objects
-   * @returns {Promise<ExtRecord<ExtType>>} The same lookup, but picking only error-free extensions
+   * @param extName - Installed extension to update
+   * @param extManifest - Fields to merge over the current entry
+   *
+   * Pass `{ write: false }` to defer flushing until a later manifest write.
    */
-  async _validate(exts) {
-    /**
-     * Lookup of extension names to {@linkcode ExtManifestProblem ExtManifestProblems}
-     * @type {Map<ExtName<ExtType>,ExtManifestProblem[]>}
-     */
-    const errorMap = new Map();
-    /**
-     * Lookup of extension names to warnings.
-     * @type {Map<ExtName<ExtType>,string[]>}
-     */
-    const warningMap = new Map();
+  async updateExtension(
+    extName: ExtName<ExtType>,
+    extManifest: ExtManifest<ExtType>,
+    {write = true}: ExtensionConfigMutationOpts = {}
+  ): Promise<void> {
+    const existing = this.installedExtensions[extName];
+    this.manifest.setExtension(this.extensionType, extName as string, {
+      ...existing,
+      ...extManifest,
+    });
+    if (write) {
+      await this.manifest.write();
+    }
+  }
+
+  /**
+   * Drops an extension from the manifest and optionally persists immediately.
+   *
+   * @param extName - Installed extension to remove
+   *
+   * Pass `{ write: false }` to defer flushing until a later manifest write.
+   */
+  async removeExtension(
+    extName: ExtName<ExtType>,
+    {write = true}: ExtensionConfigMutationOpts = {}
+  ): Promise<void> {
+    this.manifest.deleteExtension(this.extensionType, extName);
+    if (write) {
+      await this.manifest.write();
+    }
+  }
+
+  /**
+   * Logs installed extensions to the console. Subclasses may use `activeNames` to annotate active plugins.
+   */
+  print(_activeNames?: ExtName<ExtType>[]): void {
+    void _activeNames;
+    if (_.isEmpty(this.installedExtensions)) {
+      log.info(
+        `No ${this.extensionType}s have been installed in ${this.appiumHome}. Use the "appium ${this.extensionType}" ` +
+          'command to install the one(s) you want to use.'
+      );
+      return;
+    }
+
+    log.info(`Available ${this.extensionType}s:`);
+    for (const [extName, extManifest] of _.toPairs(this.installedExtensions) as Array<
+      [string, ExtManifest<ExtType>]
+    >) {
+      log.info(`  - ${this.extensionDesc(extName, extManifest)}`);
+    }
+  }
+
+  /**
+   * Root directory of an installed extension, preferring `installPath` and falling back to `node_modules/<pkgName>`.
+   *
+   * @param extName - Installed extension key
+   */
+  getInstallPath(extName: keyof ExtRecord<ExtType> & string): string {
+    return (
+      this.installedExtensions[extName]?.installPath ??
+      path.join(this.appiumHome, 'node_modules', this.installedExtensions[extName].pkgName)
+    );
+  }
+
+  /**
+   * Dynamically imports the extension entry point and returns the exported main class constructor.
+   *
+   * @param extName - Installed extension to load
+   */
+  async requireAsync(extName: ExtName<ExtType>): Promise<ExtClass<ExtType>> {
+    const [reqPath, mainClass] = await this._resolveExtension(extName);
+    log.debug(`Requiring ${this.extensionType} at ${reqPath}`);
+    // https://github.com/nodejs/node/issues/31710
+    const importPath = system.isWindows() ? pathToFileURL(reqPath).href : reqPath;
+    const mod = (await import(importPath)) as Record<string, ExtClass<ExtType>>;
+    const MainClass = mod[mainClass];
+    if (!MainClass) {
+      throw new ReferenceError(
+        `Could not find a class named "${mainClass}" exported by ${this.extensionType} "${extName}"`
+      );
+    }
+    return MainClass;
+  }
+
+  /** Whether the manifest lists an extension under the given name. */
+  isInstalled(extName: string): boolean {
+    return extName in this.installedExtensions;
+  }
+
+  /**
+   * Loads the extension’s config schema from disk or inline JSON and registers it for CLI/config validation.
+   *
+   * @param extName - Extension key
+   * @param extManifest - Manifest entry that includes `schema`
+   */
+  async readExtensionSchema(
+    extName: string,
+    extManifest: ExtManifestWithSchema<ExtType>
+  ): Promise<SchemaObject | undefined> {
+    return await ExtensionConfig._readExtensionSchema(
+      this.appiumHome,
+      this.extensionType,
+      extName,
+      extManifest
+    );
+  }
+
+  /** Optional async warnings for this extension kind; override in subclasses when needed. */
+  protected async getConfigWarnings(
+    _extManifest: ExtManifest<ExtType>,
+    _extName: string
+  ): Promise<string[]> {
+    void _extManifest;
+    void _extName;
+    return [];
+  }
+
+  /**
+   * Validates all entries in `exts`, logs summaries, and removes keys that have blocking errors.
+   * Intended for subclasses’ `validate` implementation.
+   */
+  protected async _validate(exts: ExtRecord<ExtType>): Promise<ExtRecord<ExtType>> {
+    const errorMap = new Map<string, ExtManifestProblem[]>();
+    const warningMap = new Map<string, string[]>();
 
     for (const [extName, extManifest] of _.toPairs(exts)) {
       const [errors, warnings] = await B.all([
@@ -257,18 +401,13 @@ export class ExtensionConfig {
   }
 
   /**
-   * Retrieves listing data for extensions via command class.
-   *
-   * This is an expensive operation, so the result is cached.  Currently, there is no
-   * use case for invalidating the cache.
-   * @protected
-   * @returns {Promise<import('../cli/extension-command').ExtensionList<ExtType>>}
+   * Fetches `appium driver|plugin list`-style data via the CLI command class; result is cached.
    */
-  async getListData() {
+  protected async getListData(): Promise<ExtensionList<ExtType>> {
     if (this.#listDataCache) {
       return this.#listDataCache;
     }
-    const CommandClass = /** @type {ExtCommand<ExtType>} */ (commandClasses[this.extensionType]);
+    const CommandClass = commandClasses[this.extensionType] as ExtCommand<ExtType>;
     const cmd = new CommandClass({config: this, json: true});
     const listData = await cmd.list({showInstalled: true, showUpdates: true});
     this.#listDataCache = listData;
@@ -276,20 +415,16 @@ export class ExtensionConfig {
   }
 
   /**
-   * Returns a list of warnings for a particular extension.
-   *
-   * By definition, a non-empty list of warnings does _not_ imply the extension cannot be loaded,
-   * but it may not work as expected or otherwise throw an exception at runtime.
-   *
-   * @param {ExtManifest<ExtType>} extManifest
-   * @param {ExtName<ExtType>} extName
-   * @returns {Promise<string[]>}
+   * Warnings about manifest install fields and Appium peer dependency compatibility for one extension.
    */
-  async getGenericConfigWarnings(extManifest, extName) {
+  protected async getGenericConfigWarnings(
+    extManifest: ExtManifest<ExtType>,
+    extName: string
+  ): Promise<string[]> {
     const {appiumVersion, installSpec, installType, pkgName} = extManifest;
-    const warnings = [];
+    const warnings: string[] = [];
 
-    const invalidFields = [];
+    const invalidFields: string[] = [];
     if (!_.isString(installSpec)) {
       invalidFields.push('installSpec');
     }
@@ -315,20 +450,12 @@ export class ExtensionConfig {
       );
     }
 
-    /**
-     * Helps concatenate warning messages related to peer dependencies
-     * @param {string} reason
-     * @returns string
-     */
-    const createPeerWarning = (reason) =>
+    const createPeerWarning = (reason: string): string =>
       `${extTypeText} "${extName}" (package \`${pkgName}\`) may be incompatible with the current version of Appium (v${APPIUM_VER}) due to ${reason}`;
 
     if (_.isString(appiumVersion) && !satisfies(APPIUM_VER, appiumVersion)) {
       const listData = await this.getListData();
-      const extListData =
-        /** @type {import('../cli/extension-command').ExtensionListData<ExtType>} */ (
-          listData[extName]
-        );
+      const extListData = listData[extName] as ExtensionListData<ExtType> | undefined;
       if (extListData?.installed) {
         const {updateVersion, upToDate} = extListData;
         if (!upToDate && updateVersion) {
@@ -347,10 +474,7 @@ export class ExtensionConfig {
       }
     } else if (!_.isString(appiumVersion)) {
       const listData = await this.getListData();
-      const extListData =
-        /** @type {import('../cli/extension-command').InstalledExtensionListData<ExtType>} */ (
-          listData[extName]
-        );
+      const extListData = listData[extName] as InstalledExtensionListData<ExtType> | undefined;
       if (!extListData?.upToDate && extListData?.updateVersion) {
         warnings.push(
           createPeerWarning(
@@ -369,23 +493,20 @@ export class ExtensionConfig {
     }
     return warnings;
   }
-  /**
-   * Returns list of unrecoverable errors (if any) for the given extension _if_ it has a `schema` property.
-   *
-   * @param {ExtManifest<ExtType>} extManifest - Extension data (from manifest)
-   * @param {ExtName<ExtType>} extName - Extension name (from manifest)
-   * @returns {ExtManifestProblem[]}
-   */
-  getSchemaProblems(extManifest, extName) {
-    /** @type {ExtManifestProblem[]} */
-    const problems = [];
+
+  /** Validates and registers extension CLI/config schema when the manifest defines a `schema` field. */
+  protected async getSchemaProblems(
+    extManifest: ExtManifest<ExtType>,
+    extName: string
+  ): Promise<ExtManifestProblem[]> {
+    const problems: ExtManifestProblem[] = [];
     const {schema: argSchemaPath} = extManifest;
     if (ExtensionConfig.extDataHasSchema(extManifest)) {
       if (_.isString(argSchemaPath)) {
         if (isAllowedSchemaFileExtension(argSchemaPath)) {
           try {
-            this.readExtensionSchema(extName, extManifest);
-          } catch (err) {
+            await this.readExtensionSchema(extName, extManifest);
+          } catch (err: any) {
             problems.push({
               err: `Unable to register schema at path ${argSchemaPath}; ${err.message}`,
               val: argSchemaPath,
@@ -401,8 +522,8 @@ export class ExtensionConfig {
         }
       } else if (_.isPlainObject(argSchemaPath)) {
         try {
-          this.readExtensionSchema(extName, extManifest);
-        } catch (err) {
+          await this.readExtensionSchema(extName, extManifest);
+        } catch (err: any) {
           problems.push({
             err: `Unable to register embedded schema; ${err.message}`,
             val: argSchemaPath,
@@ -418,16 +539,14 @@ export class ExtensionConfig {
     return problems;
   }
 
-  /**
-   * Return a list of generic unrecoverable errors for the given extension
-   * @param {ExtManifest<ExtType>} extManifest - Extension data (from manifest)
-   * @param {ExtName<ExtType>} extName - Extension name (from manifest)
-   * @returns {ExtManifestProblem[]}
-   */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  getGenericConfigProblems(extManifest, extName) {
+  /** Blocking issues for required manifest fields shared by all extensions (version, package name, main class). */
+  protected getGenericConfigProblems(
+    extManifest: ExtManifest<ExtType>,
+    extName: string
+  ): ExtManifestProblem[] {
+    void extName;
     const {version, pkgName, mainClass} = extManifest;
-    const problems = [];
+    const problems: ExtManifestProblem[] = [];
 
     if (!_.isString(version)) {
       problems.push({
@@ -453,139 +572,40 @@ export class ExtensionConfig {
     return problems;
   }
 
-  /**
-   * @abstract
-   * @param {ExtManifest<ExtType>} extManifest
-   * @param {ExtName<ExtType>} extName
-   * @returns {ExtManifestProblem[]}
-   */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  getConfigProblems(extManifest, extName) {
-    // should override this method if special validation is necessary for this extension type
+  /** Driver- or plugin-specific blocking validation; override in subclasses when needed. */
+  protected getConfigProblems(
+    _extManifest: ExtManifest<ExtType>,
+    _extName: string
+  ): ExtManifestProblem[] {
+    void _extManifest;
+    void _extName;
     return [];
   }
 
-  /**
-   * @param {string} extName
-   * @param {ExtManifest<ExtType>} extManifest
-   * @param {ExtensionConfigMutationOpts} opts
-   * @returns {Promise<void>}
-   */
-  async addExtension(extName, extManifest, {write = true} = {}) {
-    this.manifest.setExtension(this.extensionType, extName, extManifest);
-    if (write) {
-      await this.manifest.write();
-    }
-  }
-
-  /**
-   * @param {ExtName<ExtType>} extName
-   * @param {ExtManifest<ExtType>} extManifest
-   * @param {ExtensionConfigMutationOpts} opts
-   * @returns {Promise<void>}
-   */
-  async updateExtension(extName, extManifest, {write = true} = {}) {
-    this.manifest.setExtension(this.extensionType, extName, {
-      ...this.installedExtensions[extName],
-      ...extManifest,
-    });
-    if (write) {
-      await this.manifest.write();
-    }
-  }
-
-  /**
-   * Remove an extension from the list of installed extensions, and optionally avoid a write to the manifest file.
-   *
-   * @param {ExtName<ExtType>} extName
-   * @param {ExtensionConfigMutationOpts} opts
-   * @returns {Promise<void>}
-   */
-  async removeExtension(extName, {write = true} = {}) {
-    this.manifest.deleteExtension(this.extensionType, extName);
-    if (write) {
-      await this.manifest.write();
-    }
-  }
-
-  /**
-   * @param {ExtName<ExtType>[]} [activeNames]
-   * @returns {void}
-   */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  print(activeNames) {
-    if (_.isEmpty(this.installedExtensions)) {
-      log.info(
-        `No ${this.extensionType}s have been installed in ${this.appiumHome}. Use the "appium ${this.extensionType}" ` +
-          'command to install the one(s) you want to use.'
-      );
-      return;
-    }
-
-    log.info(`Available ${this.extensionType}s:`);
-    for (const [extName, extManifest] of /** @type {[string, ExtManifest<ExtType>][]} */ (
-      _.toPairs(this.installedExtensions)
-    )) {
-      log.info(`  - ${this.extensionDesc(extName, extManifest)}`);
-    }
-  }
-
-  /**
-   * Returns a string describing the extension. Subclasses must implement.
-   * @param {ExtName<ExtType>} extName - Extension name
-   * @param {ExtManifest<ExtType>} extManifest - Extension data
-   * @returns {string}
-   * @abstract
-   */
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  extensionDesc(extName, extManifest) {
-    throw new Error('This must be implemented in a subclass');
-  }
-
-  /**
-   * 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 (
-      this.installedExtensions[extName]?.installPath ??
-      path.join(this.appiumHome, 'node_modules', this.installedExtensions[extName].pkgName)
-    );
-  }
-
-  /**
-   *
-   * @param {ExtName<ExtType>} extName
-   * @returns {Promise<[string, string]>}
-   */
-  async _resolveExtension(extName) {
+  private async _resolveExtension(extName: ExtName<ExtType>): Promise<[string, string]> {
     const {mainClass} = this.installedExtensions[extName];
     const moduleRoot = this.getInstallPath(extName);
     const packageJsonPath = path.join(moduleRoot, 'package.json');
-    let extensionManifest;
+    let extensionManifest: Record<string, any>;
     try {
       extensionManifest = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
-    } catch (e) {
+    } catch (e: any) {
       throw new ReferenceError(
         `Could not read the ${this.extensionType} manifest at ${packageJsonPath}: ${e.message}`
       );
     }
-    /** @type {string | undefined} */
-    let entryPointRelativePath;
+    let entryPointRelativePath: string | undefined;
     try {
       if (extensionManifest.type === 'module' && extensionManifest.exports) {
         entryPointRelativePath = resolveEsmEntryPoint(extensionManifest.exports);
       }
       entryPointRelativePath = entryPointRelativePath ?? extensionManifest.main ?? DEFAULT_ENTRY_POINT;
-    } catch (e) {
+    } catch (e: any) {
       throw new ReferenceError(
         `Could not find the ${this.extensionType} installed at ${moduleRoot}: ${e.message}`
       );
     }
-    const entryPointFullPath = path.resolve(moduleRoot, /** @type {string} */ (entryPointRelativePath));
+    const entryPointFullPath = path.resolve(moduleRoot, entryPointRelativePath as string);
     if (!await fs.exists(entryPointFullPath)) {
       throw new ReferenceError(
         `Cannot find a valid ${this.extensionType} main entry point in '${packageJsonPath}'. ` +
@@ -601,98 +621,21 @@ export class ExtensionConfig {
   }
 
   /**
-   * Loads extension asynchronously and returns its main class (constructor)
+   * One-line human description for list output; implemented per extension kind.
    *
-   * @param {ExtName<ExtType>} extName
-   * @returns {Promise<ExtClass<ExtType>>}
-   */
-  async requireAsync(extName) {
-    const [reqPath, mainClass] = await this._resolveExtension(extName);
-    log.debug(`Requiring ${this.extensionType} at ${reqPath}`);
-    // https://github.com/nodejs/node/issues/31710
-    const importPath = system.isWindows() ? pathToFileURL(reqPath).href : reqPath;
-    const MainClass = (await import(importPath))[mainClass];
-    if (!MainClass) {
-      throw new ReferenceError(
-        `Could not find a class named "${mainClass}" exported by ${this.extensionType} "${extName}"`
-      );
-    }
-    return MainClass;
-  }
-
-  /**
-   * @param {string} extName
-   * @returns {boolean}
+   * @param extName - Manifest key
+   * @param extManifest - Entry used for version and kind-specific labels
    */
-  isInstalled(extName) {
-    return extName in this.installedExtensions;
-  }
+  public abstract extensionDesc(extName: ExtName<ExtType>, extManifest: ExtManifest<ExtType>): string;
 
-  /**
-   * Intended to be called by corresponding instance methods of subclass.
-   * @private
-   * @template {ExtensionType} ExtType
-   * @param {string} appiumHome
-   * @param {ExtType} extType
-   * @param {ExtName<ExtType>} extName - Extension name (unique to its type)
-   * @param {ExtManifestWithSchema<ExtType>} extManifest - Extension config
-   * @returns {import('ajv').SchemaObject|undefined}
-   */
-  static _readExtensionSchema(appiumHome, extType, extName, extManifest) {
-    const {pkgName, schema: argSchemaPath} = extManifest;
-    if (!argSchemaPath) {
-      throw new TypeError(
-        `No \`schema\` property found in config for ${extType} ${pkgName} -- why is this function being called?`
-      );
-    }
-    let moduleObject;
-    if (_.isString(argSchemaPath)) {
-      const schemaPath = resolveFrom(appiumHome, path.join(pkgName, argSchemaPath));
-      moduleObject = require(schemaPath);
-    } else {
-      moduleObject = argSchemaPath;
-    }
-    // this sucks. default exports should be destroyed
-    const schema = moduleObject.__esModule ? moduleObject.default : moduleObject;
-    registerSchema(extType, extName, schema);
-    return schema;
-  }
-
-  /**
-   * Returns `true` if a specific {@link ExtManifest} object has a `schema` prop.
-   * The {@link ExtManifest} object becomes a {@link ExtManifestWithSchema} object.
-   * @template {ExtensionType} ExtType
-   * @param {ExtManifest<ExtType>} extManifest
-   * @returns {extManifest is ExtManifestWithSchema<ExtType>}
-   */
-  static extDataHasSchema(extManifest) {
-    return _.isString(extManifest?.schema) || _.isObject(extManifest?.schema);
-  }
-
-  /**
-   * If an extension provides a schema, this will load the schema and attempt to
-   * register it with the schema registrar.
-   * @param {ExtName<ExtType>} extName - Name of extension
-   * @param {ExtManifestWithSchema<ExtType>} extManifest - Extension data
-   * @returns {import('ajv').SchemaObject|undefined}
-   */
-  readExtensionSchema(extName, extManifest) {
-    return ExtensionConfig._readExtensionSchema(
-      this.appiumHome,
-      this.extensionType,
-      extName,
-      extManifest
-    );
-  }
 }
 
 /**
- * https://nodejs.org/api/packages.html#package-entry-points
+ * Resolves a package `exports` field (string, `"."`, or `"import"`) to a relative entry path for ESM packages.
  *
- * @param {any} exportsValue
- * @returns {string | undefined}
+ * @param exportsValue - `package.json` `exports` value or nested fragment
  */
-export function resolveEsmEntryPoint(exportsValue) {
+export function resolveEsmEntryPoint(exportsValue: unknown): string | undefined {
   if (_.isString(exportsValue) && exportsValue) {
     return exportsValue;
   }
@@ -700,67 +643,10 @@ export function resolveEsmEntryPoint(exportsValue) {
     return;
   }
 
-  for (const key of ['.', 'import']) {
-    if (exportsValue[key]) {
-      return resolveEsmEntryPoint(exportsValue[key]);
+  const obj = exportsValue as Record<string, unknown>;
+  for (const key of ['.', 'import'] as const) {
+    if (obj[key]) {
+      return resolveEsmEntryPoint(obj[key]);
     }
   }
 }
-
-/**
- * An issue with the {@linkcode ExtManifest} for a particular extension.
- *
- * The existance of such an object implies that the extension cannot be loaded.
- * @typedef ExtManifestProblem
- * @property {string} err - Error message
- * @property {any} val - Associated value
- */
-
-/**
- * An optional logging function provided to an {@link ExtensionConfig} subclass.
- * @callback ExtensionLogFn
- * @param {...any} args
- * @returns {void}
- */
-
-/**
- * @typedef {import('@appium/types').ExtensionType} ExtensionType
- * @typedef {import('./manifest').Manifest} Manifest
- * @typedef {import('appium/types').InstallType} InstallType
- */
-
-/**
- * @template {ExtensionType} ExtType
- * @typedef {import('appium/types').ExtManifest<ExtType>} ExtManifest
- */
-
-/**
- * @template {ExtensionType} ExtType
- * @typedef {ExtManifest<ExtType> & {schema: NonNullable<ExtManifest<ExtType>['schema']>}} ExtManifestWithSchema
- */
-
-/**
- * @template {ExtensionType} ExtType
- * @typedef {import('appium/types').ExtName<ExtType>} ExtName
- */
-
-/**
- * @template {ExtensionType} ExtType
- * @typedef {import('appium/types').ExtClass<ExtType>} ExtClass
- */
-
-/**
- * @template {ExtensionType} ExtType
- * @typedef {import('appium/types').ExtRecord<ExtType>} ExtRecord
- */
-
-/**
- * @template {ExtensionType} ExtType
- * @typedef {import('../cli/extension').ExtCommand<ExtType>} ExtCommand
- */
-
-/**
- * Options for various methods in {@link ExtensionConfig}
- * @typedef ExtensionConfigMutationOpts
- * @property {boolean} [write=true] Whether or not to write the manifest to disk after a mutation operation
- */