appium 2.0.0-beta.46 → 2.0.0-beta.47

package/lib/utils.js

@@ -4,6 +4,7 @@ import {processCapabilities, PROTOCOLS, STANDARD_CAPS} from '@appium/base-driver
 import {inspect as dump} from 'util';
 import {node} from '@appium/support';
 import path from 'path';
+import {SERVER_SUBCOMMAND, DRIVER_TYPE, PLUGIN_TYPE} from './constants';
 
 const W3C_APPIUM_PREFIX = 'appium';
 const STANDARD_CAPS_LOWERCASE = new Set([...STANDARD_CAPS].map((cap) => cap.toLowerCase()));
@@ -289,6 +290,46 @@ function pullSettings(caps) {
   return result;
 }
 
+/**
+ * @template {CliCommand} [Cmd=ServerCommand]
+ * @template {CliExtensionSubcommand|void} [SubCmd=void]
+ * @param {Args<Cmd, SubCmd>} args
+ * @returns {args is Args<ServerCommand>}
+ */
+export function isServerCommandArgs(args) {
+  return args.subcommand === SERVER_SUBCOMMAND;
+}
+
+/**
+ * @template {CliCommand} [Cmd=ServerCommand]
+ * @template {CliExtensionSubcommand|void} [SubCmd=void]
+ * @param {Args<Cmd, SubCmd>} args
+ * @returns {args is Args<CliExtensionCommand, SubCmd>}
+ */
+export function isExtensionCommandArgs(args) {
+  return args.subcommand === DRIVER_TYPE || args.subcommand === PLUGIN_TYPE;
+}
+
+/**
+ * @template {CliCommand} Cmd
+ * @template {CliExtensionSubcommand} SubCmd
+ * @param {Args<Cmd, SubCmd>} args
+ * @returns {args is Args<DriverCommand, SubCmd>}
+ */
+export function isDriverCommandArgs(args) {
+  return args.subcommand === DRIVER_TYPE;
+}
+
+/**
+ * @template {CliCommand} Cmd
+ * @template {CliExtensionSubcommand} SubCmd
+ * @param {Args<Cmd, SubCmd>} args
+ * @returns {args is Args<PluginCommand, SubCmd>}
+ */
+export function isPluginCommandArgs(args) {
+  return args.subcommand === PLUGIN_TYPE;
+}
+
 export {
   inspect,
   parseCapsForInnerDriver,
@@ -357,3 +398,24 @@ export {
 /**
  * @typedef {import('@appium/types').Constraints} Constraints
  */
+
+/**
+ * @typedef {import('appium/types').CliCommand} CliCommand
+ * @typedef {import('appium/types').CliExtensionSubcommand} CliExtensionSubcommand
+ * @typedef {import('appium/types').CliExtensionCommand} CliExtensionCommand
+ * @typedef {import('appium/types').ServerCommand} ServerCommand
+ * @typedef {import('appium/types').DriverCommand} DriverCommand
+ * @typedef {import('appium/types').PluginCommand} PluginCommand
+ */
+
+/**
+ * @template {CliCommand} [Cmd=ServerCommand]
+ * @template {CliExtensionSubcommand|void} [SubCmd=void]
+ * @typedef {import('appium/types').Args<Cmd, SubCmd>} Args
+ */
+
+/**
+ * @template {CliCommand} [Cmd=ServerCommand]
+ * @template {CliExtensionSubcommand|void} [SubCmd=void]
+ * @typedef {import('appium/types').ParsedArgs<Cmd, SubCmd>} ParsedArgs
+ */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium",
-  "version": "2.0.0-beta.46",
+  "version": "2.0.0-beta.47",
   "description": "Automation for Apps.",
   "keywords": [
     "automation",
@@ -41,19 +41,15 @@
     "types"
   ],
   "scripts": {
-    "build": "babel lib --root-mode=upward --out-dir=build/lib",
     "build:docs": "node docs/scripts/build-docs.js",
-    "build:docs:cli": "node docs/scripts/gen-cli-args-docs.js",
     "build:docs:assets": "node docs/scripts/copy-assets.js",
-    "dev": "npm run build -- --watch",
+    "build:docs:cli": "node docs/scripts/gen-cli-args-docs.js",
+    "build:docs:reference": "node docs/scripts/build-reference.js",
     "dev:docs": "npm run build:docs:assets && npm run dev:docs:en",
     "dev:docs:en": "mkdocs serve -f ./docs/mkdocs-en.yml",
     "dev:docs:ja": "mkdocs serve -f ./docs/mkdocs-ja.yml",
     "dev:docs:zh": "mkdocs serve -f ./docs/mkdocs-zh.yml",
-    "fix": "npm run lint -- --fix",
     "postinstall": "node ./scripts/autoinstall-extensions.js",
-    "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",
-    "prepare": "npm run build",
     "publish:docs": "cross-env APPIUM_DOCS_PUBLISH=1 npm run build:docs",
     "test": "npm run test:unit",
     "test:e2e": "mocha --timeout 1m --slow 30s \"./test/e2e/**/*.spec.js\"",
@@ -61,25 +57,25 @@
     "test:unit": "mocha \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/base-driver": "^8.7.3",
-    "@appium/base-plugin": "^1.10.5",
-    "@appium/docutils": "^0.0.13",
-    "@appium/schema": "^0.0.9",
-    "@appium/support": "^2.61.1",
-    "@appium/types": "^0.5.0",
+    "@appium/base-driver": "^9.0.0",
+    "@appium/base-plugin": "^2.0.0",
+    "@appium/docutils": "^0.1.0",
+    "@appium/schema": "^0.1.0",
+    "@appium/support": "^3.0.0",
+    "@appium/types": "^0.6.0",
     "@sidvind/better-ajv-errors": "2.1.0",
     "@types/argparse": "2.0.10",
-    "@types/bluebird": "3.5.37",
+    "@types/bluebird": "3.5.38",
     "@types/fancy-log": "2.0.0",
-    "@types/semver": "7.3.12",
-    "@types/teen_process": "1.16.1",
+    "@types/semver": "7.3.13",
+    "@types/teen_process": "2.0.0",
     "@types/wrap-ansi": "3.0.0",
-    "ajv": "8.11.0",
+    "ajv": "8.11.2",
     "ajv-formats": "2.1.1",
     "argparse": "2.0.1",
-    "async-lock": "1.3.2",
-    "asyncbox": "2.9.2",
-    "axios": "0.27.2",
+    "async-lock": "1.4.0",
+    "asyncbox": "2.9.4",
+    "axios": "1.2.1",
     "bluebird": "3.7.2",
     "cross-env": "7.0.3",
     "find-up": "5.0.0",
@@ -87,25 +83,28 @@
     "lilconfig": "2.0.6",
     "lodash": "4.17.21",
     "longjohn": "0.2.12",
-    "npmlog": "6.0.2",
+    "npmlog": "7.0.1",
     "ora": "5.4.1",
     "package-changed": "1.9.0",
     "resolve-from": "5.0.0",
     "semver": "7.3.8",
     "source-map-support": "0.5.21",
     "teen_process": "2.0.2",
-    "type-fest": "3.1.0",
+    "type-fest": "3.3.0",
     "winston": "3.8.2",
     "wrap-ansi": "7.0.0",
     "yaml": "2.1.3"
   },
   "engines": {
-    "node": ">=14",
+    "node": "^14.17.0 || ^16.13.0 || >=18.0.0",
     "npm": ">=8"
   },
   "publishConfig": {
     "access": "public",
     "tag": "next"
   },
-  "gitHead": "6b3cc1a8743f78c1f50320364f25f3011d2b2136"
+  "gitHead": "0823f0b60e40395cd1dc3b72cfa3c0092bc81302",
+  "typedoc": {
+    "entryPoint": "./build/lib/main.js"
+  }
 }

package/scripts/autoinstall-extensions.js

@@ -14,10 +14,24 @@
  * code upon failure (which will typically break a build).  Otherwise, it
  * will always exit with code 0, even if errors occur.
  *
+ * @module
  * @example
  * `npm install -g appium --drivers=uiautomator2,xcuitest --plugins=images`
  */
 
+const path = require('path');
+const {exec} = require('teen_process');
+const B = require('bluebird');
+
+B.config({
+  cancellation: true,
+});
+
+/**
+ * This is only used if we're actually in the monorepo
+ */
+const MONOREPO_ROOT = path.join(__dirname, '..', '..', '..');
+
 /** @type {import('../lib/cli/extension').runExtensionCommand} */
 let runExtensionCommand;
 /** @type {import('../lib/constants').DRIVER_TYPE} */
@@ -27,44 +41,82 @@ let PLUGIN_TYPE;
 /** @type {import('../lib/extension').loadExtensions} */
 let loadExtensions;
 
-const {env, util, logger} = require('@appium/support');
 const _ = require('lodash');
 const wrap = _.partial(
   require('wrap-ansi'),
   _,
-  process.stderr.columns ?? process.stdout.columns ?? 25
+  process.stderr.columns ?? process.stdout.columns ?? 80
 );
-
 const ora = require('ora');
 
-const log = (message) => {
+let env, util, logger;
+
+function log(message) {
   console.error(wrap(`[Appium] ${message}`));
-};
-
-const spinner = ora({
-  text: 'Checking Appium installation...',
-  prefixText: '[Appium]',
-}).start();
-
-try {
-  ({runExtensionCommand} = require('../build/lib/cli/extension'));
-  ({DRIVER_TYPE, PLUGIN_TYPE} = require('../build/lib/constants'));
-  ({loadExtensions} = require('../build/lib/extension'));
-  spinner.succeed('Appium installation OK');
-  // suppress logs from Appium, which mess up the script output
-  logger.getLogger('Appium').level = 'error';
-} catch (e) {
-  spinner.fail(`Could not load required module(s); has Appium been built? (${e.message})`);
-  if (process.env.CI) {
-    console.error('Detected CI environment, exiting with code 1');
-    process.exitCode = 1;
-  } else {
-    process.exitCode = 0;
+}
+
+async function init() {
+  /** @type {import('ora').Ora} */
+  let spinner;
+
+  try {
+    ({env, util, logger} = require('@appium/support'));
+    require('..');
+  } catch {
+    spinner = ora({
+      text: 'Building Appium dev environment...',
+      prefixText: '[Appium]',
+    }).start();
+
+    try {
+      const {stderr, code} = await exec('npm', ['run', 'build'], {
+        cwd: MONOREPO_ROOT,
+        encoding: 'utf8',
+      });
+      if (!code) {
+        spinner.succeed('Appium build successfully.');
+      } else {
+        spinner.fail(`Building Appium failed!`);
+        log(stderr);
+      }
+    } catch (err) {
+      spinner.fail(`Building Appium failed!`);
+      log(err);
+    }
+  }
+
+  spinner = ora({
+    text: 'Checking Appium installation...',
+    prefixText: '[Appium]',
+  }).start();
+
+  try {
+    ({env, util, logger} = require('@appium/support'));
+    ({runExtensionCommand} = require('../build/lib/cli/extension'));
+    ({DRIVER_TYPE, PLUGIN_TYPE} = require('../build/lib/constants'));
+    ({loadExtensions} = require('../build/lib/extension'));
+    spinner.succeed('Appium installation OK');
+    // suppress logs from Appium, which mess up the script output
+    logger.getLogger('Appium').level = 'error';
+  } catch (e) {
+    spinner.fail(`Could not load required module(s); has Appium been built? (${e.message})`);
+    if (process.env.CI) {
+      log('Detected CI environment, exiting with code 1');
+      process.exitCode = 1;
+    } else {
+      process.exitCode = 0;
+    }
+    return false;
   }
-  process.exit();
+
+  return true;
 }
 
 async function main() {
+  if (!(await init())) {
+    return;
+  }
+
   // if we're doing `npm install -g appium` then we will assume we don't have a local appium.
   if (!process.env.npm_config_global && (await env.hasAppiumDependency())) {
     log(`Found local Appium installation; skipping automatic installation of extensions.`);

package/types/cli.ts

@@ -1,23 +1,39 @@
-import {ServerArgs} from '@appium/types';
-export type ServerSubcommand = 'server';
-export type DriverSubcommand = 'driver';
-export type PluginSubcommand = 'plugin';
+import {DriverType, PluginType, ServerArgs} from '@appium/types';
+import {SetOptional} from 'type-fest';
+import {InstallType} from './manifest';
+export type ServerCommand = 'server';
+export type DriverCommand = DriverType;
+export type PluginCommand = PluginType;
 
 /**
- * Possible subcommands for the `appium` CLI.
+ * Extension-specific commands
  */
-export type CliSubcommand = ServerSubcommand | DriverSubcommand | PluginSubcommand;
+export type CliExtensionCommand = DriverCommand | PluginCommand;
 
 /**
- * Possible subcommands of {@linkcode DriverSubcommand} or
- * {@linkcode PluginSubcommand}.
+ * Possible commands for the `appium` CLI.
  */
-export type CliExtensionSubcommand =
-  | 'install'
-  | 'list'
-  | 'run'
-  | 'uninstall'
-  | 'update';
+export type CliCommand = ServerCommand | CliExtensionCommand;
+
+/**
+ * Possible subcommands of {@linkcode DriverCommand} or
+ * {@linkcode PluginCommand}.
+ */
+export type CliExtensionSubcommand = 'install' | 'list' | 'run' | 'uninstall' | 'update';
+
+export interface CliExtensionSubcommandListArgs {
+  showInstalled?: boolean;
+  showUpdates?: boolean;
+}
+
+export interface CliExtensionSubcommandInstallArgs {
+  installType: InstallType;
+  packageName?: string;
+}
+
+export interface CliExtensionSubcommandUpdateArgs {
+  unsafe?: boolean;
+}
 
 /**
  * Random stuff that may appear in the parsed args which has no equivalent in a
@@ -25,9 +41,9 @@ export type CliExtensionSubcommand =
  */
 export interface MoreArgs {
   /**
-   * Possible subcommands. If empty, defaults to {@linkcode ServerSubcommand}.
+   * Possible subcommands. If empty, defaults to {@linkcode ServerCommand}.
    */
-  subcommand?: CliSubcommand;
+  subcommand?: CliCommand;
 
   /**
    * Path to config file, if any. Does not make sense for this to be allowed in a config file!
@@ -79,19 +95,21 @@ export interface ProgrammaticArgs {
   showConfig?: boolean;
 }
 
+export interface DriverExtArgs {
+  driverCommand: CliExtensionSubcommand;
+  driver?: string;
+}
+
+export interface PluginExtArgs {
+  pluginCommand: CliExtensionSubcommand;
+  plugin?: string;
+}
+
 /**
  * These are args which the user will specify if using an extension command
  */
-export interface ExtArgs extends WithExtSubcommand {
-  /**
-   * Subcommands of `driver` subcommand
-   */
-  driverCommand?: CliExtensionSubcommand;
-
-  /**
-   * Subcommands of `plugin` subcommand
-   */
-  pluginCommand?: CliExtensionSubcommand;
+export interface BaseExtArgs<Cmd extends CliExtensionCommand> {
+  subcommand: Cmd;
 
   /**
    * Output JSON instead of human-readable text
@@ -110,35 +128,56 @@ export interface ExtArgs extends WithExtSubcommand {
 }
 
 /**
- * Args having the `server` subcommand
+ * Args for extension commands; includes a subcommand
  */
-export interface WithServerSubcommand {
-  subcommand?: ServerSubcommand;
-}
-
-/**
- * Args having the `driver` or `plugin` subcommand
- */
-export interface WithExtSubcommand {
-  subcommand: DriverSubcommand | PluginSubcommand;
-}
+export type ExtArgs<
+  Cmd extends CliExtensionCommand,
+  SubCmd extends CliExtensionSubcommand
+> = BaseExtArgs<Cmd> &
+  (Cmd extends DriverCommand ? DriverExtArgs : Cmd extends PluginCommand ? PluginExtArgs : never) &
+  (SubCmd extends 'install'
+    ? CliExtensionSubcommandInstallArgs
+    : SubCmd extends 'list'
+    ? CliExtensionSubcommandListArgs
+    : SubCmd extends 'update'
+    ? CliExtensionSubcommandUpdateArgs
+    : never);
 
 /**
  * Some generic bits of arguments; should not be used outside this declaration
  */
-type CommonArgs<SArgs, T = WithServerSubcommand> = MoreArgs &
+export type CommonArgs<
+  Cmd extends CliCommand = ServerCommand,
+  SubCmd extends CliExtensionSubcommand | void = void
+> = MoreArgs &
   ProgrammaticArgs &
-  (T extends WithServerSubcommand ? SArgs : T extends WithExtSubcommand ? ExtArgs : never);
+  (Cmd extends ServerCommand
+    ? ServerArgs
+    : Cmd extends CliExtensionCommand
+    ? SubCmd extends CliExtensionSubcommand
+      ? ExtArgs<Cmd, SubCmd>
+      : never
+    : never);
 
 /**
  * Fully-parsed arguments, containing defaults, computed args, and config file values.
  */
-export type ParsedArgs<T = WithServerSubcommand> = CommonArgs<ServerArgs, T>;
+export type ParsedArgs<
+  Cmd extends CliCommand = ServerCommand,
+  SubCmd extends CliExtensionSubcommand | void = void
+> = CommonArgs<Cmd, SubCmd>;
 
 /**
- * Partial arguments, as supplied by a user. _May_ have defaults applied; _may_ contain config values; _may_ contain computed args.
+ * Like {@linkcode ParsedArgs} except server arguments are all optional.
+ *
+ * _May_ have defaults applied; _may_ contain config values; _may_ contain computed args.
  */
-export type Args<T = WithServerSubcommand> = CommonArgs<Partial<ServerArgs>, T>;
+export type Args<
+  Cmd extends CliCommand = ServerCommand,
+  SubCmd extends CliExtensionSubcommand | void = void
+> = Cmd extends ServerCommand
+  ? SetOptional<CommonArgs<Cmd>, keyof ServerArgs>
+  : ParsedArgs<Cmd, SubCmd>;
 
 /**
  * Shown by `appium --build-info`

package/types/index.ts

@@ -1,7 +1,6 @@
 import {ExtensionType, DriverType, DriverClass, PluginType, PluginClass} from '@appium/types';
 
-export * from './appium-manifest';
-export * from './extension-manifest';
+export * from './manifest';
 export * from './cli';
 
 /**

package/types/manifest/README.md

@@ -0,0 +1,30 @@
+# appium-manifest types
+
+This dir contains versioned type declarations for our manifest file (`extensions.yaml`).
+
+## About
+
+Originally, the manifest file was versioned; it had a `schemaRev` prop.  Eventually, the requirement for this prop was dropped, and became optional.  As of this writing, it is now required again.  
+
+The idea was that if Appium found an `extensions.yaml` with a `schemaRev` lower than its "current" revision, it would "migrate" the file to the current revision.  When we removed the requirement for the `schemaRev` prop, we removed this logic.
+
+As of _v3_ of the schema, we are reinstating versioning and migrations.
+
+## How To Add A New Version
+
+The manifest file types—and thus its format—is composed of types used elsewhere in our codebase.  This is probably a design flaw, but the fact remains that the manifest file's format is strongly coupled to Appium's extension-handling logic.
+
+For that reason, it is _non-trivial_ to reuse the types declared by older revisions to declare a new revision.  If and when someone de-couples the types from the schema, we will have to use the _copy-and-paste_ strategy to create a new version.
+
+1. The current version of the schema is defined in `constants.js` as `CURRENT_SCHEMA_REV`.  **Increment** this value.
+2. **Copy** the `.ts` file in this directory corresponding to the (now old) current version of the schema into a new file named `v<new-version>.ts`.  For example, if the current version is `3`, and you're creating `4`, then you would copy `v3.ts` to `v4.ts`.
+3. **Modify** your new file to do whatever it is you need to do with it.  Do _not_ build types upon old versions of the schema.
+4. **Modify** `index.ts`:
+   1. **Append** `import * as ManifestV<new-version> from './v<new-version>'`
+   2. **Replace** `export * from './v<current-version>'` with `export * from './v<new-version>'`
+   3. **Append** `ManifestV<new-version>` to the `export {ManifestV...}` line.
+   4. **Append** a key/value pair to `ManifestDataVersions` with the new _numeric_ version number as the key and the value `ManifestV<new-version>.ManifestData`.
+5. **Create** a new `const SCHEMA_REV_<new-version> = <new-version>` in `manifest-migrations.js`.
+6. Finally, **append** a new key/value pair to the `Migrations` object in `manifest-migrations.js`.  The key should be a reference to the constant created in step 5, and the value should be a function which  performs the migration from the (old) current version to the new version.
+
+-- @boneskull, Nov 8 2022

package/types/manifest/base.ts

@@ -0,0 +1,158 @@
+import {DriverType, ExtensionType, PluginType} from '@appium/types';
+import {SchemaObject} from 'ajv';
+import {PackageJson, SetRequired} from 'type-fest';
+
+/**
+ * One of the possible extension installation stratgies
+ */
+export type InstallType = 'npm' | 'git' | 'local' | 'github';
+
+export interface InternalMetadata {
+  /**
+   * Package name of extension
+   *
+   * `name` from its `package.json`
+   */
+  pkgName: string;
+  /**
+   * Version of extension
+   *
+   * `version` from its `package.json`
+   */
+  version: string;
+  /**
+   * The method in which the user installed the extension (the `source` CLI arg)
+   */
+  installType: InstallType;
+  /**
+   * Whatever the user typed as the extension to install. May be derived from `package.json`
+   */
+  installSpec: string;
+  /**
+   * Maximum version of Appium that this extension is compatible with.
+   *
+   * If `undefined`, we'll try anyway.
+   */
+  appiumVersion?: string;
+}
+
+/**
+ * Shape of the `appium.schema` property in an extension's `package.json` (if it exists)
+ */
+export type ExtSchemaMetadata = string | (SchemaObject & {[key: number]: never});
+
+/**
+ * Manifest data shared by all extensions, as contained in `package.json`
+ */
+export interface CommonExtMetadata {
+  /**
+   * The main class of the extension.
+   *
+   * The extension must export this class by name.
+   */
+  mainClass: string;
+
+  /**
+   * Lookup table of scripts to run via `appium <driver|plugin> run <script>` keyed by name.
+   */
+  scripts?: Record<string, string>;
+
+  /**
+   * Schema describing configuration options (and CLI args) for the extension.
+   *
+   * Can also just be a path (relative to the extension root) to an external JSON schema file.
+   */
+
+  schema?: ExtSchemaMetadata;
+}
+
+/**
+ * Driver-specific manifest data as stored in a driver's `package.json`
+ */
+export interface DriverMetadata {
+  /**
+   * Automation name of the driver
+   */
+  automationName: string;
+  /**
+   * Platforms the driver supports
+   */
+  platformNames: string[];
+  /**
+   * Short name of the driver (displayed in `appium list`, etc.)
+   */
+  driverName: string;
+}
+
+/**
+ * Plugin-specific manifest data as stored in a plugin's `package.json`
+ */
+export interface PluginMetadata {
+  /**
+   * Short name of the plugin (displayed in `appium list`, etc.)
+   */
+  pluginName: string;
+}
+
+/**
+ * Generic extension metadata as stored in the `appium` prop of an extension's `package.json`.
+ */
+export type ExtMetadata<ExtType extends ExtensionType> = (ExtType extends DriverType
+  ? DriverMetadata
+  : ExtType extends PluginType
+  ? PluginMetadata
+  : never) &
+  CommonExtMetadata;
+
+/**
+ * Combination of external + internal extension data with `driverName`/`pluginName` removed (it becomes a key in an {@linkcode ExtRecord} object).
+ * Part of `extensions.yaml`.
+ */
+export type ExtManifest<ExtType extends ExtensionType> = Omit<
+  ExtMetadata<ExtType>,
+  'driverName' | 'pluginName'
+> &
+  InternalMetadata;
+
+/**
+ * Lookup of extension name to {@linkcode ExtManifest}.
+ * @see {ManifestData}
+ */
+export type ExtRecord<ExtType extends ExtensionType> = Record<string, ExtManifest<ExtType>>;
+
+/**
+ * The shape of the `extensions.yaml` file
+ */
+export interface ManifestData {
+  drivers: ExtRecord<DriverType>;
+  plugins: ExtRecord<PluginType>;
+  schemaRev?: number;
+}
+
+/**
+ * The name of an installed extension, as it appears in `extensions.yaml`
+ * (as a property name under `drivers` or `plugins`)
+ */
+export type ExtName<ExtType extends ExtensionType> = keyof ExtRecord<ExtType>;
+
+/**
+ * A `package.json` containing extension metadata.
+ * Must have the following properties:
+ * - `name`: the name of the extension
+ * - `version`: the version of the extension
+ * - `appium`: the metadata for the extension
+ * - `peerDependencies.appium`: the maximum compatible version of Appium
+ */
+export type ExtPackageJson<ExtType extends ExtensionType> = SetRequired<
+  PackageJson,
+  'name' | 'version'
+> & {
+  appium: ExtMetadata<ExtType>;
+  peerDependencies: {appium: string; [key: string]: string};
+};
+
+/**
+ * A transient format between installation and insertion of extension metadata into the manifest.
+ */
+export type ExtInstallReceipt<ExtType extends ExtensionType> = ExtMetadata<ExtType> &
+  InternalMetadata;