appium 3.3.0 → 3.3.1

package/lib/bidi-commands.ts

@@ -5,11 +5,7 @@ import {errors} from '@appium/base-driver';
 import {BIDI_BASE_PATH, BIDI_EVENT_NAME} from './constants';
 import WebSocket from 'ws';
 import os from 'node:os';
-import {
-  isBroadcastIp,
-  fetchInterfaces,
-  V4_BROADCAST_IP,
-} from './utils';
+import {isBroadcastIp, fetchInterfaces, V4_BROADCAST_IP} from './helpers/network';
 import type {IncomingMessage} from 'node:http';
 import type {AppiumDriver} from './appium';
 import type {
@@ -99,15 +95,6 @@ export function onBidiConnection(this: AppiumDriver, ws: WebSocket, req: Incomin
   }
 }
 
-function wrapCommandWithPlugins(driver: ExtensionCore, plugins: ExtensionCore[], method: string, params: StringRecord): () => Promise<BiDiResultData> {
-    const [moduleName, methodName] = method.split('.');
-    let next = async () => await driver.executeBidiCommand(method, params);
-    for (const plugin of plugins.filter((p) => p.doesBidiCommandExist(moduleName, methodName))) {
-      next = ((_next) => async () => await plugin.executeBidiCommand(method, params, _next, driver))(next);
-    }
-    return next;
-}
-
 /**
  * @param data
  * @param driver
@@ -204,6 +191,15 @@ export function cleanupBidiSockets(this: AppiumDriver, sessionId: string): void
   delete this.bidiProxyClients[sessionId];
 }
 
+function wrapCommandWithPlugins(driver: ExtensionCore, plugins: ExtensionCore[], method: string, params: StringRecord): () => Promise<BiDiResultData> {
+  const [moduleName, methodName] = method.split('.');
+  let next = async () => await driver.executeBidiCommand(method, params);
+  for (const plugin of plugins.filter((p) => p.doesBidiCommandExist(moduleName, methodName))) {
+    next = ((_next) => async () => await plugin.executeBidiCommand(method, params, _next, driver))(next);
+  }
+  return next;
+}
+
 // #region Private functions
 
 /**

package/lib/bootstrap/appium-initializer.ts

@@ -0,0 +1,212 @@
+import {init as logsinkInit} from '../logsink';
+import {log as logger} from '../logger';
+import {util, env} from '@appium/support';
+import _ from 'lodash';
+import type {DriverOpts} from '@appium/types';
+import {AppiumDriver, type AppiumDriverConstraints} from '../appium';
+import {runExtensionCommand} from '../cli/extension';
+import {runSetupCommand} from '../cli/setup-command';
+import {getParser, ArgParser} from '../cli/parser';
+import {readConfigFile} from './config-file';
+import {getNonDefaultServerArgs, showConfig} from './startup-config';
+import {adjustNodePath, requireDir, showDebugInfo} from './node-helpers';
+import {loadExtensions, type ExtensionConfigs} from '../extension';
+import {SERVER_SUBCOMMAND} from '../constants';
+import {injectAppiumSymlinks} from '../cli/extension-command';
+import {getDefaultsForSchema} from '../schema/schema';
+import {
+  isDriverCommandArgs,
+  isExtensionCommandArgs,
+  isPluginCommandArgs,
+  isServerCommandArgs,
+  isSetupCommandArgs,
+} from '../schema/cli-args-guards';
+import type {
+  Args,
+  CliCommand,
+  CliCommandServer,
+  CliCommandSetupSubcommand,
+  CliExtensionSubcommand,
+  ParsedArgs,
+} from 'appium/types';
+import {determineAppiumHomeSource, preflightChecks} from './main-helpers';
+import type {InitResult, PreConfigArgs} from './init-types';
+
+/**
+ * Parses CLI/programmatic args, loads config and extensions, and returns server-ready state or runs extension/setup flows.
+ */
+export class AppiumInitializer {
+  private throwInsteadOfExit = false;
+
+  /**
+   * Resolves Appium home, loads config, and either returns server-ready state for the server subcommand
+   * or performs setup/extension CLI work and returns an empty result.
+   *
+   * @param args - Optional programmatic args; when omitted, parses `process.argv`
+   */
+  async init<
+    Cmd extends CliCommand = CliCommandServer,
+    SubCmd extends CliExtensionSubcommand | CliCommandSetupSubcommand | void = void,
+  >(args?: Args<Cmd, SubCmd>): Promise<InitResult<Cmd>> {
+    this.throwInsteadOfExit = false;
+
+    const appiumHome = args?.appiumHome ?? (await env.resolveAppiumHome());
+    const appiumHomeSourceName = determineAppiumHomeSource(args?.appiumHome);
+    await requireDir(appiumHome, false, appiumHomeSourceName);
+
+    adjustNodePath();
+
+    const {driverConfig, pluginConfig} = await loadExtensions(appiumHome);
+
+    const {preConfigArgs, throwInsteadOfExit} = await this.parsePreConfigArgs(args);
+    this.throwInsteadOfExit = throwInsteadOfExit;
+
+    const configResult = await readConfigFile(preConfigArgs.configFile);
+    this.assertConfigFileOk(configResult);
+
+    if (isServerCommandArgs(preConfigArgs)) {
+      return this.finishServerInit(
+        preConfigArgs,
+        configResult,
+        driverConfig,
+        pluginConfig,
+        appiumHome,
+        appiumHomeSourceName,
+      );
+    }
+
+    if (isSetupCommandArgs(preConfigArgs)) {
+      await runSetupCommand(preConfigArgs, driverConfig, pluginConfig);
+      return {} as InitResult<Cmd>;
+    }
+
+    await requireDir(appiumHome, true, appiumHomeSourceName);
+    await this.runExtensionCliIfNeeded(preConfigArgs, driverConfig, pluginConfig);
+    return {} as InitResult<Cmd>;
+  }
+
+  private async parsePreConfigArgs<
+    Cmd extends CliCommand,
+    SubCmd extends CliExtensionSubcommand | CliCommandSetupSubcommand | void,
+  >(args?: Args<Cmd, SubCmd>): Promise<{preConfigArgs: PreConfigArgs; throwInsteadOfExit: boolean}> {
+    const parser = await getParser();
+    let throwInsteadOfExit = false;
+
+    if (args) {
+      if (args.throwInsteadOfExit) {
+        throwInsteadOfExit = true;
+        delete args.throwInsteadOfExit;
+      }
+      const preConfigArgs = {...args, subcommand: args.subcommand ?? SERVER_SUBCOMMAND} as PreConfigArgs;
+      ArgParser.normalizeServerArgs(preConfigArgs);
+      return {preConfigArgs, throwInsteadOfExit};
+    }
+
+    return {preConfigArgs: parser.parseArgs() as PreConfigArgs, throwInsteadOfExit};
+  }
+
+  private assertConfigFileOk(configResult: Awaited<ReturnType<typeof readConfigFile>>): void {
+    if (!_.isEmpty(configResult.errors)) {
+      throw new Error(
+        `Errors in config file ${configResult.filepath}:\n ${configResult.reason ?? configResult.errors}`,
+      );
+    }
+  }
+
+  private async finishServerInit<Cmd extends CliCommand>(
+    preConfigArgs: PreConfigArgs,
+    configResult: Awaited<ReturnType<typeof readConfigFile>>,
+    driverConfig: ExtensionConfigs['driverConfig'],
+    pluginConfig: ExtensionConfigs['pluginConfig'],
+    appiumHome: string,
+    appiumHomeSourceName: string,
+  ): Promise<InitResult<Cmd>> {
+    const defaults = getDefaultsForSchema(false);
+    const serverArgs = _.defaultsDeep(
+      {},
+      preConfigArgs,
+      configResult.config?.server,
+      defaults,
+    ) as ParsedArgs<CliCommandServer>;
+
+    if (preConfigArgs.showConfig) {
+      showConfig(getNonDefaultServerArgs(preConfigArgs as Args), configResult, defaults, serverArgs);
+      return {} as InitResult<Cmd>;
+    }
+
+    if (preConfigArgs.showDebugInfo) {
+      await showDebugInfo({
+        driverConfig,
+        pluginConfig,
+        appiumHome,
+      });
+      return {} as InitResult<Cmd>;
+    }
+
+    await logsinkInit(serverArgs);
+    await this.applyLogFilters(serverArgs);
+
+    if (!serverArgs.noPermsCheck) {
+      await requireDir(appiumHome, true, appiumHomeSourceName);
+    }
+
+    const appiumDriver = new AppiumDriver(serverArgs as DriverOpts<AppiumDriverConstraints>);
+    appiumDriver.driverConfig = driverConfig;
+    await preflightChecks(serverArgs, this.throwInsteadOfExit);
+
+    return {
+      appiumDriver,
+      parsedArgs: serverArgs,
+      driverConfig,
+      pluginConfig,
+      appiumHome,
+    } as InitResult<Cmd>;
+  }
+
+  private async applyLogFilters(serverArgs: ParsedArgs<CliCommandServer>): Promise<void> {
+    if (!serverArgs.logFilters) {
+      return;
+    }
+    const {issues, rules} = await logger.unwrap().loadSecureValuesPreprocessingRules(serverArgs.logFilters);
+    const argToLog = _.truncate(JSON.stringify(serverArgs.logFilters), {
+      length: 150,
+    });
+    if (!_.isEmpty(issues)) {
+      throw new Error(
+        `The log filtering rules config ${argToLog} has issues: ` + JSON.stringify(issues, null, 2),
+      );
+    }
+    if (_.isEmpty(rules)) {
+      logger.warn(
+        `Found no log filtering rules in the ${argToLog} config. ` + `Is that expected?`,
+      );
+    } else {
+      logger.info(`Loaded ${util.pluralize('filtering rule', rules.length, true)}`);
+    }
+  }
+
+  private async runExtensionCliIfNeeded(
+    preConfigArgs: PreConfigArgs,
+    driverConfig: ExtensionConfigs['driverConfig'],
+    pluginConfig: ExtensionConfigs['pluginConfig'],
+  ): Promise<void> {
+    if (!isExtensionCommandArgs(preConfigArgs)) {
+      return;
+    }
+    if (isDriverCommandArgs(preConfigArgs)) {
+      await runExtensionCommand(preConfigArgs, driverConfig);
+    }
+    if (isPluginCommandArgs(preConfigArgs)) {
+      await runExtensionCommand(preConfigArgs, pluginConfig);
+    }
+
+    if (isDriverCommandArgs(preConfigArgs) || isPluginCommandArgs(preConfigArgs)) {
+      const cmd = isDriverCommandArgs(preConfigArgs)
+        ? preConfigArgs.driverCommand
+        : preConfigArgs.pluginCommand;
+      if (cmd === 'install') {
+        await injectAppiumSymlinks(driverConfig, pluginConfig, logger);
+      }
+    }
+  }
+}

package/lib/bootstrap/appium-main-runner.ts

@@ -0,0 +1,172 @@
+import {log as logger} from '../logger';
+import _ from 'lodash';
+import type {AppiumServer} from '@appium/types';
+import {getActivePlugins, getActiveDrivers} from '../extension';
+import registerNode from './grid-v3-register';
+import {
+  determineAppiumHomeSource,
+  logStartupInfo,
+  buildServerOpts,
+  createAppiumServer,
+  logServerAddress,
+} from './main-helpers';
+import type {InitResult, ServerInitData} from './init-types';
+import type {
+  Args,
+  CliCommand,
+  CliCommandServer,
+  CliCommandSetupSubcommand,
+  CliExtensionSubcommand,
+} from 'appium/types';
+import type {ServerOpts} from '@appium/base-driver';
+import net from 'node:net';
+
+const MAX_SERVER_PROCESS_LISTENERS = 100;
+
+/**
+ * Starts the Appium HTTP server after {@link AppiumInitializer.init}: loads drivers/plugins, binds, grid register, signals.
+ */
+export class AppiumMainRunner {
+  /**
+   * For server init: builds listeners, registers with Grid 3 if configured, and returns the server.
+   * For non-server commands, `initResult` is empty and this resolves to `undefined`.
+   *
+   * @param initResult - Output of {@link AppiumInitializer.init}
+   * @param args - Original args (used to describe `appiumHome` source in logs)
+   */
+  async run<
+    Cmd extends CliCommand = CliCommandServer,
+    SubCmd extends CliExtensionSubcommand | CliCommandSetupSubcommand | void = void,
+  >(initResult: InitResult<Cmd>, args?: Args<Cmd, SubCmd>): Promise<Cmd extends CliCommandServer ? AppiumServer : void> {
+    if (_.isEmpty(initResult)) {
+      return undefined as Cmd extends CliCommandServer ? AppiumServer : void;
+    }
+
+    const {appiumDriver, pluginConfig, driverConfig, parsedArgs, appiumHome} = initResult as ServerInitData;
+
+    const pluginClasses = await getActivePlugins(
+      pluginConfig,
+      parsedArgs.pluginsImportChunkSize,
+      parsedArgs.usePlugins,
+    );
+    for (const [pluginClass, name] of pluginClasses) {
+      appiumDriver.pluginClasses.set(pluginClass, name);
+    }
+
+    await logStartupInfo(parsedArgs);
+
+    appiumDriver.configureGlobalFeatures();
+
+    const appiumHomeSourceName = determineAppiumHomeSource(args?.appiumHome);
+    logger.debug(`The ${appiumHomeSourceName}: ${appiumHome}`);
+
+    const driverClasses = await getActiveDrivers(
+      driverConfig,
+      parsedArgs.driversImportChunkSize,
+      parsedArgs.useDrivers,
+    );
+    const {serverOpts, normalizedBasePath} = buildServerOpts(
+      appiumDriver,
+      parsedArgs,
+      driverClasses,
+      pluginClasses,
+    );
+
+    const server = await this.startHttpServer(serverOpts, appiumDriver, normalizedBasePath);
+    if (!server) {
+      return undefined as Cmd extends CliCommandServer ? AppiumServer : void;
+    }
+
+    this.warnIfCorsEnabled(parsedArgs);
+    appiumDriver.server = server;
+
+    await this.registerGridOrClose(server, parsedArgs, normalizedBasePath);
+    this.attachSignalHandlers(appiumDriver, server);
+    this.logListeningUrl(server, parsedArgs, normalizedBasePath);
+
+    driverConfig.print();
+    pluginConfig.print([...pluginClasses.values()]);
+
+    return server as Cmd extends CliCommandServer ? AppiumServer : void;
+  }
+
+  private async startHttpServer(
+    serverOpts: ServerOpts,
+    appiumDriver: ServerInitData['appiumDriver'],
+    normalizedBasePath: string,
+  ): Promise<AppiumServer | undefined> {
+    try {
+      return await createAppiumServer(serverOpts, appiumDriver, normalizedBasePath);
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      const stack = err instanceof Error ? err.stack : undefined;
+      logger.error(
+        `Could not configure Appium server. It's possible that a driver or plugin tried ` +
+          `to update the server and failed. Original error: ${message}`,
+      );
+      logger.debug(stack);
+      process.exit(1);
+      return undefined;
+    }
+  }
+
+  private warnIfCorsEnabled(parsedArgs: ServerInitData['parsedArgs']): void {
+    if (parsedArgs.allowCors) {
+      logger.warn(
+        'You have enabled CORS requests from any host. Be careful not ' +
+          'to visit sites which could maliciously try to start Appium ' +
+          'sessions on your machine',
+      );
+    }
+  }
+
+  private async registerGridOrClose(
+    server: AppiumServer,
+    parsedArgs: ServerInitData['parsedArgs'],
+    normalizedBasePath: string,
+  ): Promise<void> {
+    try {
+      if (parsedArgs.nodeconfig) {
+        await registerNode(
+          parsedArgs.nodeconfig,
+          parsedArgs.address,
+          parsedArgs.port,
+          normalizedBasePath,
+        );
+      }
+    } catch (err: unknown) {
+      await server.close();
+      throw err;
+    }
+  }
+
+  private attachSignalHandlers(
+    appiumDriver: ServerInitData['appiumDriver'],
+    server: AppiumServer,
+  ): void {
+    process.setMaxListeners(MAX_SERVER_PROCESS_LISTENERS);
+    for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+      process.once(signal, async function onSignal() {
+        logger.info(`Received ${signal} - shutting down`);
+        try {
+          await appiumDriver.shutdown(`The process has received ${signal} signal`);
+          await server.close();
+          process.exit(0);
+        } catch (e: unknown) {
+          logger.warn(e);
+          process.exit(1);
+        }
+      });
+    }
+  }
+
+  private logListeningUrl(
+    server: AppiumServer,
+    parsedArgs: ServerInitData['parsedArgs'],
+    normalizedBasePath: string,
+  ): void {
+    const protocol = server.isSecure() ? 'https' : 'http';
+    const address = net.isIPv6(parsedArgs.address) ? `[${parsedArgs.address}]` : parsedArgs.address;
+    logServerAddress(`${protocol}://${address}:${parsedArgs.port}${normalizedBasePath}`);
+  }
+}

package/lib/{config-file.ts → bootstrap/config-file.ts}

@@ -1,48 +1,49 @@
-import betterAjvErrors, {type IOutputError} from '@sidvind/better-ajv-errors';
+import type {IOutputError} from '@sidvind/better-ajv-errors';
 import type {ErrorObject, SchemaObject} from 'ajv';
 import {lilconfig, type LoaderSync, type LilconfigResult} from 'lilconfig';
 import _ from 'lodash';
 import * as yaml from 'yaml';
 import type {AppiumConfig, NormalizedAppiumConfig} from '@appium/types';
-import {getSchema, validate} from './schema/schema';
+import {getSchema, validate} from '../schema/schema';
+import {formatErrors} from '../schema/format-errors';
 
 /**
  * A cache of the raw config file (a JSON string) at a filepath.
  * This is used for better error reporting.
  * Note that config files needn't be JSON, but it helps if they are.
  */
-const rawConfig = new Map<string, RawJson>();
+const rawConfig = new Map<string, string>();
 
 /**
- * Given an array of errors and the result of loading a config file, generate a
- * helpful string for the user.
- *
- * - If `opts` contains a `json` property, this should be the original JSON
- *   _string_ of the config file.  This is only applicable if the config file
- *   was in JSON format. If present, it will associate line numbers with errors.
- * - If `errors` happens to be empty, this will throw.
- *
- * @throws {TypeError} If `errors` is empty
+ * Result of calling {@link readConfigFile}.
  */
-export function formatErrors(
-  errors: ErrorObject[] = [],
-  config: ReadConfigFileResult['config'] | Record<string, unknown> | string = {},
-  opts: FormatConfigErrorsOptions = {}
-): string | IOutputError[] {
-  if (errors && !errors.length) {
-    throw new TypeError('Array of errors must be non-empty');
-  }
-  return betterAjvErrors(getSchema(opts.schemaId), config, errors, {
-    json: opts.json,
-    format: opts.pretty === false ? 'js' : 'cli',
-  });
+export interface ReadConfigFileResult {
+  errors?: ErrorObject[];
+  filepath?: string;
+  isEmpty?: boolean;
+  config?: NormalizedAppiumConfig;
+  reason?: string | IOutputError[];
+}
+
+/**
+ * Options for {@link readConfigFile}.
+ */
+export interface ReadConfigFileOptions {
+  pretty?: boolean;
 }
 
+/**
+ * This is an `AsyncSearcher` which is inexplicably _not_ exported by the `lilconfig` type definition.
+ */
+type LilconfigAsyncSearcher = ReturnType<typeof lilconfig>;
+
 /**
  * Given an optional path, read a config file. Validates the config file.
  *
  * Call {@link validate} if you already have a config object.
  * @public
+ * @param filepath - Explicit config path; when omitted, searches with lilconfig
+ * @param opts - e.g. `pretty` for formatted validation errors
  * @returns Contains config and filepath, if found, and any errors
  */
 export async function readConfigFile(
@@ -89,8 +90,10 @@ export async function readConfigFile(
 }
 
 /**
- * Convert schema property names to either a) the value of the `appiumCliDest` property, if any; or b) camel-case
- * @returns New object with camel-cased keys (or `dest` keys).
+ * Converts schema property names to either the `appiumCliDest` value, if any, or camelCase.
+ *
+ * @param config - Raw config object as parsed from file
+ * @returns New object with camel-cased keys (or CLI `dest` keys).
  */
 export function normalizeConfig(config: AppiumConfig): NormalizedAppiumConfig {
   const schema = getSchema();
@@ -173,40 +176,3 @@ async function loadConfigFile(lc: LilconfigAsyncSearcher, filepath: string): Pro
 async function searchConfigFile(lc: LilconfigAsyncSearcher): Promise<LilconfigResult> {
   return await lc.search();
 }
-
-/**
- * Result of calling {@link readConfigFile}.
- */
-export interface ReadConfigFileResult {
-  errors?: ErrorObject[];
-  filepath?: string;
-  isEmpty?: boolean;
-  config?: NormalizedAppiumConfig;
-  reason?: string | IOutputError[];
-}
-
-/**
- * Options for {@link readConfigFile}.
- */
-export interface ReadConfigFileOptions {
-  pretty?: boolean;
-}
-
-/**
- * The string should be a raw JSON string.
- */
-export type RawJson = string;
-
-/**
- * Options for {@link formatErrors}.
- */
-export interface FormatConfigErrorsOptions {
-  json?: RawJson;
-  pretty?: boolean;
-  schemaId?: string;
-}
-
-/**
- * This is an `AsyncSearcher` which is inexplicably _not_ exported by the `lilconfig` type definition.
- */
-type LilconfigAsyncSearcher = ReturnType<typeof lilconfig>;

package/lib/{grid-register.ts → bootstrap/grid-v3-register.ts}

@@ -2,7 +2,7 @@ import axios from 'axios';
 import {fs} from '@appium/support';
 import type {StringRecord} from '@appium/types';
 import _ from 'lodash';
-import logger from './logger';
+import {log as logger} from '../logger';
 
 /**
  * Selenium **Grid 3** (legacy hub) node integration.
@@ -18,6 +18,40 @@ import logger from './logger';
 const GRID_V3_REGISTER_PATH = '/grid/register';
 const GRID_V3_PROXY_API_PATH = '/grid/api/proxy';
 
+interface Grid3HubConfiguration {
+  hubProtocol?: string;
+  hubHost?: string;
+  hubPort?: number;
+  url?: string;
+  host?: string;
+  port?: number;
+  id?: string;
+  register?: boolean;
+  registerCycle?: number;
+}
+
+interface Grid3NodeConfig extends StringRecord {
+  configuration?: Grid3HubConfiguration;
+  capabilities?: unknown;
+}
+
+interface Grid3ProxyApiResponse {
+  success: boolean;
+  msg?: string;
+}
+
+export default async function registerNode(
+  data: string,
+  addr: string,
+  port: number,
+  basePath: string
+): Promise<void>;
+export default async function registerNode(
+  data: Grid3NodeConfig,
+  addr?: string,
+  port?: number,
+  basePath?: string
+): Promise<void>;
 /**
  * Registers this server as a node with a **Selenium Grid 3** hub.
  *
@@ -33,18 +67,6 @@ const GRID_V3_PROXY_API_PATH = '/grid/api/proxy';
  * @param port - Bind to this port
  * @param basePath - Base path for the Appium server (used in the node URL sent to the hub; may be `''`)
  */
-export default async function registerNode(
-  data: string,
-  addr: string,
-  port: number,
-  basePath: string
-): Promise<void>;
-export default async function registerNode(
-  data: Grid3NodeConfig,
-  addr?: string,
-  port?: number,
-  basePath?: string
-): Promise<void>;
 export default async function registerNode(
   data: string | Grid3NodeConfig,
   addr?: string,
@@ -226,25 +248,3 @@ async function isAlreadyRegistered(configHolder: Grid3NodeConfig): Promise<boole
     logger.debug(`Selenium Grid 3 hub down or not responding: ${(err as Error).message}`);
   }
 }
-
-interface Grid3HubConfiguration {
-  hubProtocol?: string;
-  hubHost?: string;
-  hubPort?: number;
-  url?: string;
-  host?: string;
-  port?: number;
-  id?: string;
-  register?: boolean;
-  registerCycle?: number;
-}
-
-interface Grid3NodeConfig extends StringRecord {
-  configuration?: Grid3HubConfiguration;
-  capabilities?: unknown;
-}
-
-interface Grid3ProxyApiResponse {
-  success: boolean;
-  msg?: string;
-}

package/lib/bootstrap/init-types.ts

@@ -0,0 +1,31 @@
+import type {AppiumDriver} from '../appium';
+import type {
+  Args,
+  CliCommand,
+  CliCommandServer,
+  CliCommandSetupSubcommand,
+  CliExtensionSubcommand,
+  ParsedArgs,
+} from 'appium/types';
+import type {ExtensionConfigs} from '../extension';
+
+/** Empty object returned when `init` completes for non-server CLI flows (extension/setup). */
+export type ExtCommandInitResult = Record<string, never>;
+
+/** Driver/plugin config plus server instance and merged server args after successful server `init`. */
+export type ServerInitData = ExtensionConfigs & {
+  appiumDriver: AppiumDriver;
+  parsedArgs: ParsedArgs<CliCommandServer>;
+  appiumHome: string;
+};
+
+/** Discriminated by CLI command: server subcommand yields {@link ServerInitData}; otherwise {@link ExtCommandInitResult}. */
+export type InitResult<Cmd extends CliCommand = CliCommandServer> = Cmd extends CliCommandServer
+  ? ServerInitData
+  : ExtCommandInitResult;
+
+/** CLI + programmatic args before `init` narrows by `subcommand`. */
+export type PreConfigArgs = Args<
+  CliCommand,
+  CliExtensionSubcommand | CliCommandSetupSubcommand | void
+>;