appium-mac2-driver 4.5.1 → 4.6.0

package/node_modules/appium-chromedriver/lib/commands/binary.ts

@@ -0,0 +1,379 @@
+import path from 'node:path';
+
+import {fs, util} from '@appium/support';
+import {asyncmap} from 'asyncbox';
+import * as semver from 'semver';
+import {type ExecError} from 'teen_process';
+
+import type {ChromedriverVersionMapping} from '../types.js';
+import {CHROMEDRIVER_CHROME_MAPPING, getChromedriverBinaryPath, compareVersions} from '../utils.js';
+import type {ChromedriverCommandContext} from './types.js';
+
+const NEW_CD_VERSION_FORMAT_MAJOR_VERSION = 73;
+const CD_VERSION_TIMEOUT = 5000;
+const GET_COMPATIBLE_CHROMEDRIVER_MAX_ITERATIONS = 10;
+
+export interface ChromedriverInfo {
+  executable: string;
+  version: string;
+  minChromeVersion: string | null;
+}
+
+type ChromedriverSelectionSelf = ChromedriverCommandContext & {
+  getDriversMapping: () => Promise<ChromedriverVersionMapping>;
+  getChromedrivers: (mapping: ChromedriverVersionMapping) => Promise<ChromedriverInfo[]>;
+  updateDriversMapping: (mapping: ChromedriverVersionMapping) => Promise<void>;
+  getChromeVersion: () => Promise<semver.SemVer | null>;
+  getCompatibleChromedriver: () => Promise<string>;
+};
+
+/**
+ * Loads and normalizes Chromedriver-to-Chrome version mapping.
+ */
+export async function getDriversMapping(this: ChromedriverCommandContext): Promise<ChromedriverVersionMapping> {
+  let mapping = structuredClone(CHROMEDRIVER_CHROME_MAPPING);
+  if (this.mappingPath) {
+    this.log.debug(`Attempting to use Chromedriver->Chrome mapping from '${this.mappingPath}'`);
+    if (!(await fs.exists(this.mappingPath))) {
+      this.log.warn(`No file found at '${this.mappingPath}'`);
+      this.log.info('Defaulting to the static Chromedriver->Chrome mapping');
+    } else {
+      try {
+        mapping = JSON.parse(await fs.readFile(this.mappingPath, 'utf8'));
+      } catch (e) {
+        const err = e as Error;
+        this.log.warn(`Error parsing mapping from '${this.mappingPath}': ${err.message}`);
+        this.log.info('Defaulting to the static Chromedriver->Chrome mapping');
+      }
+    }
+  } else {
+    this.log.debug('Using the static Chromedriver->Chrome mapping');
+  }
+
+  for (const [cdVersion, chromeVersion] of Object.entries(mapping)) {
+    const coercedVersion = semver.coerce(chromeVersion);
+    if (coercedVersion) {
+      mapping[cdVersion] = coercedVersion.version;
+    } else {
+      this.log.info(`'${chromeVersion}' is not a valid version number. Skipping it`);
+    }
+  }
+  return mapping;
+}
+
+/**
+ * Discovers available Chromedriver binaries and parses their versions.
+ */
+export async function getChromedrivers(
+  this: ChromedriverCommandContext,
+  mapping: ChromedriverVersionMapping,
+): Promise<ChromedriverInfo[]> {
+  // enumerate available executables in configured chromedriver directory
+  const executables = await fs.glob('*', {
+    cwd: this.executableDir,
+    nodir: true,
+    absolute: true,
+  });
+  this.log.debug(`Found ${util.pluralize('executable', executables.length, true)} in '${this.executableDir}'`);
+  const cds = (
+    await asyncmap(executables, async (executable: string) => {
+      const logError = ({message, stdout, stderr}: {message: string; stdout?: string; stderr?: string}): null => {
+        let errMsg =
+          `Cannot retrieve version number from '${path.basename(executable)}' Chromedriver binary. ` +
+          `Make sure it returns a valid version string in response to '--version' command line argument. ${message}`;
+        if (stdout) {
+          errMsg += `\nStdout: ${stdout}`;
+        }
+        if (stderr) {
+          errMsg += `\nStderr: ${stderr}`;
+        }
+        this.log.warn(errMsg);
+        return null;
+      };
+
+      let stdout: string;
+      let stderr: string | undefined;
+      try {
+        ({stdout, stderr} = await this._execFunc(executable, ['--version'], {
+          timeout: CD_VERSION_TIMEOUT,
+        }));
+      } catch (e) {
+        const err = e as ExecError;
+        if (!(err.message || '').includes('timed out') && !(err.stdout || '').includes('Starting ChromeDriver')) {
+          return logError(err);
+        }
+        // timeouts may still contain the version banner in stdout
+        stdout = err.stdout;
+      }
+
+      const match = /ChromeDriver\s+\(?v?([\d.]+)\)?/i.exec(stdout);
+      if (!match) {
+        return logError({message: 'Cannot parse the version string', stdout, stderr});
+      }
+      let version = match[1];
+      let minChromeVersion = mapping[version] || null;
+      const coercedVersion = semver.coerce(version);
+      if (coercedVersion) {
+        if (coercedVersion.major < NEW_CD_VERSION_FORMAT_MAJOR_VERSION) {
+          version = `${coercedVersion.major}.${coercedVersion.minor}`;
+          minChromeVersion = mapping[version] || null;
+        }
+        if (!minChromeVersion && coercedVersion.major >= NEW_CD_VERSION_FORMAT_MAJOR_VERSION) {
+          minChromeVersion = `${coercedVersion.major}`;
+        }
+      }
+      return {executable, version, minChromeVersion};
+    })
+  )
+    .filter((cd): cd is ChromedriverInfo => !!cd)
+    .sort((a, b) => compareVersions(b.version, a.version));
+  if (cds.length === 0) {
+    this.log.info(`No Chromedrivers were found in '${this.executableDir}'`);
+    return cds;
+  }
+  this.log.debug(`The following Chromedriver executables were found:`);
+  for (const cd of cds) {
+    this.log.debug(
+      `    '${cd.executable}' (version '${cd.version}', minimum Chrome version '${
+        cd.minChromeVersion ? cd.minChromeVersion : 'Unknown'
+      }')`,
+    );
+  }
+  return cds;
+}
+
+/**
+ * Persists updated version mapping to disk or falls back to in-memory update.
+ */
+export async function updateDriversMapping(
+  this: ChromedriverCommandContext,
+  newMapping: ChromedriverVersionMapping,
+): Promise<void> {
+  let shouldUpdateStaticMapping = true;
+  if (!this.mappingPath) {
+    this.log.warn('No mapping path provided');
+    return;
+  }
+  if (await fs.exists(this.mappingPath)) {
+    try {
+      await fs.writeFile(this.mappingPath, JSON.stringify(newMapping, null, 2), 'utf8');
+      shouldUpdateStaticMapping = false;
+    } catch (e) {
+      const err = e as Error;
+      this.log.warn(
+        `Cannot store the updated chromedrivers mapping into '${this.mappingPath}'. ` +
+          `This may reduce the performance of further executions. Original error: ${err.message}`,
+      );
+    }
+  }
+  if (shouldUpdateStaticMapping) {
+    Object.assign(CHROMEDRIVER_CHROME_MAPPING, newMapping);
+  }
+}
+
+/**
+ * Selects the most suitable Chromedriver binary for current environment.
+ */
+export async function getCompatibleChromedriver(this: ChromedriverCommandContext): Promise<string> {
+  if (usesDesktopChromedriverDefault(this)) {
+    return await getChromedriverBinaryPath();
+  }
+
+  const ctx = this as ChromedriverSelectionSelf;
+  const mapping = await ctx.getDriversMapping();
+  if (!util.isEmpty(mapping)) {
+    ctx.log.debug(`The most recent known Chrome version: ${Object.values(mapping)[0]}`);
+  }
+
+  const syncState = {didStorageSync: false};
+
+  for (let iteration = 0; iteration < GET_COMPATIBLE_CHROMEDRIVER_MAX_ITERATIONS; iteration++) {
+    const cds = await ctx.getChromedrivers(mapping);
+    await mergeDiscoveredMappingGaps(ctx, cds, mapping);
+
+    if (ctx.disableBuildCheck) {
+      return pickChromedriverWithBuildCheckDisabled(ctx, cds);
+    }
+
+    const chromeVersion = await ctx.getChromeVersion();
+    if (!chromeVersion) {
+      return pickChromedriverWhenChromeUnknown(ctx, cds);
+    }
+    ctx.log.debug(`Found Chrome bundle '${ctx.bundleId}' version '${chromeVersion}'`);
+
+    const matchingDrivers = filterChromedriversMatchingChrome(cds, chromeVersion);
+    if (matchingDrivers.length === 0) {
+      if (ctx.storageClient && !syncState.didStorageSync) {
+        try {
+          if (await attemptChromedriverStorageSync(ctx, mapping, chromeVersion, syncState)) {
+            continue;
+          }
+        } catch (e) {
+          const err = e as Error;
+          ctx.log.warn(`Cannot synchronize local chromedrivers with the remote storage: ${err.message}`);
+          if (err.stack) {
+            ctx.log.debug(err.stack);
+          }
+        }
+      }
+      throw makeNoMatchingChromedriverError(ctx, chromeVersion);
+    }
+
+    return logChosenMatchingChromedriver(ctx, matchingDrivers, chromeVersion);
+  }
+
+  throw new Error(
+    `Exceeded ${GET_COMPATIBLE_CHROMEDRIVER_MAX_ITERATIONS} iterations while selecting a compatible Chromedriver.`,
+  );
+}
+
+/**
+ * Resolves and verifies the effective Chromedriver executable path.
+ */
+export async function initChromedriverPath(this: ChromedriverCommandContext): Promise<string> {
+  if (this.executableVerified && this.chromedriver) {
+    return this.chromedriver;
+  }
+  let chromedriver = this.chromedriver;
+  if (!chromedriver) {
+    chromedriver = this.chromedriver = this.useSystemExecutable
+      ? await getChromedriverBinaryPath()
+      : await (this as ChromedriverSelectionSelf).getCompatibleChromedriver();
+  }
+  if (!chromedriver) {
+    throw new Error('Cannot determine a valid Chromedriver executable path');
+  }
+  if (!(await fs.exists(chromedriver))) {
+    throw new Error(`Trying to use a chromedriver binary at the path ${chromedriver}, but it doesn't exist!`);
+  }
+  this.executableVerified = true;
+  this.log.info(`Set chromedriver binary as: ${chromedriver}`);
+  return chromedriver;
+}
+
+function usesDesktopChromedriverDefault(ctx: ChromedriverCommandContext): boolean {
+  return !ctx.adb && !ctx.isCustomExecutableDir;
+}
+
+async function mergeDiscoveredMappingGaps(
+  ctx: ChromedriverSelectionSelf,
+  cds: ChromedriverInfo[],
+  mapping: ChromedriverVersionMapping,
+): Promise<void> {
+  const missingVersions: ChromedriverVersionMapping = {};
+  for (const {version, minChromeVersion} of cds) {
+    if (!minChromeVersion || mapping[version]) {
+      continue;
+    }
+    const coercedVer = semver.coerce(version);
+    if (!coercedVer || coercedVer.major < NEW_CD_VERSION_FORMAT_MAJOR_VERSION) {
+      continue;
+    }
+    missingVersions[version] = minChromeVersion;
+  }
+  const missingCount = Object.keys(missingVersions).length;
+  if (missingCount === 0) {
+    return;
+  }
+  ctx.log.info(
+    `Found ${util.pluralize('Chromedriver', missingCount, true)}, ` +
+      `which ${missingCount === 1 ? 'is' : 'are'} missing in the list of known versions: ` +
+      JSON.stringify(missingVersions),
+  );
+  await ctx.updateDriversMapping(Object.assign(mapping, missingVersions));
+}
+
+function pickChromedriverWithBuildCheckDisabled(ctx: ChromedriverSelectionSelf, cds: ChromedriverInfo[]): string {
+  if (cds.length === 0) {
+    throw ctx.log.errorWithException(
+      `There must be at least one Chromedriver executable available for use if ` +
+        `'chromedriverDisableBuildCheck' capability is set to 'true'`,
+    );
+  }
+  const {version, executable} = cds[0];
+  ctx.log.warn(`Chrome build check disabled. Using most recent Chromedriver version (${version}, at '${executable}')`);
+  ctx.log.warn(`If this is wrong, set 'chromedriverDisableBuildCheck' capability to 'false'`);
+  return executable;
+}
+
+function pickChromedriverWhenChromeUnknown(ctx: ChromedriverSelectionSelf, cds: ChromedriverInfo[]): string {
+  if (cds.length === 0) {
+    throw ctx.log.errorWithException(
+      `There must be at least one Chromedriver executable available for use if ` +
+        `the current Chrome version cannot be determined`,
+    );
+  }
+  const {version, executable} = cds[0];
+  ctx.log.warn(`Unable to discover Chrome version. Using Chromedriver ${version} at '${executable}'`);
+  return executable;
+}
+
+function filterChromedriversMatchingChrome(cds: ChromedriverInfo[], chromeVersion: semver.SemVer): ChromedriverInfo[] {
+  return cds.filter(({minChromeVersion}) => {
+    const minChromeVersionS = minChromeVersion && semver.coerce(minChromeVersion);
+    if (!minChromeVersionS) {
+      return false;
+    }
+    return chromeVersion.major > NEW_CD_VERSION_FORMAT_MAJOR_VERSION
+      ? minChromeVersionS.major === chromeVersion.major
+      : semver.gte(chromeVersion, minChromeVersionS);
+  });
+}
+
+/**
+ * Syncs drivers from remote storage into `mapping` and persists when possible.
+ * Sets `syncState.didStorageSync` before any early return so a second sync is not attempted.
+ */
+async function attemptChromedriverStorageSync(
+  ctx: ChromedriverSelectionSelf,
+  mapping: ChromedriverVersionMapping,
+  chromeVersion: semver.SemVer,
+  syncState: {didStorageSync: boolean},
+): Promise<boolean> {
+  syncState.didStorageSync = true;
+  if (!ctx.storageClient) {
+    return false;
+  }
+  const retrievedMapping = await ctx.storageClient.retrieveMapping();
+  ctx.log.debug(
+    'Got chromedrivers mapping from the storage: ' +
+      util.truncateString(JSON.stringify(retrievedMapping, null, 2), {length: 500}),
+  );
+  const driverKeys = await ctx.storageClient.syncDrivers({
+    minBrowserVersion: chromeVersion.major,
+  });
+  if (driverKeys.length === 0) {
+    return false;
+  }
+  const synchronizedDriversMapping = driverKeys.reduce((acc, x) => {
+    const {version, minBrowserVersion} = retrievedMapping[x];
+    acc[version] = minBrowserVersion;
+    return acc;
+  }, {} as ChromedriverVersionMapping);
+  Object.assign(mapping, synchronizedDriversMapping);
+  await ctx.updateDriversMapping(mapping);
+  return true;
+}
+
+function makeNoMatchingChromedriverError(ctx: ChromedriverSelectionSelf, chromeVersion: semver.SemVer): Error {
+  const autodownloadSuggestion =
+    'You could also try to enable automated chromedrivers download as a possible workaround.';
+  return new Error(
+    `No Chromedriver found that can automate Chrome '${chromeVersion}'.` +
+      (ctx.storageClient ? '' : ` ${autodownloadSuggestion}`),
+  );
+}
+
+function logChosenMatchingChromedriver(
+  ctx: ChromedriverSelectionSelf,
+  matchingDrivers: ChromedriverInfo[],
+  chromeVersion: semver.SemVer,
+): string {
+  const binPath = matchingDrivers[0].executable;
+  ctx.log.debug(
+    `Found ${util.pluralize('executable', matchingDrivers.length, true)} ` +
+      `capable of automating Chrome '${chromeVersion}'.\nChoosing the most recent, '${binPath}'.`,
+  );
+  ctx.log.debug(`If a specific version is required, specify it with the 'chromedriverExecutable' capability.`);
+  return binPath;
+}

package/node_modules/appium-chromedriver/lib/commands/process.ts

@@ -0,0 +1,110 @@
+import {system, util} from '@appium/support';
+import {retryInterval} from 'asyncbox';
+import {exec} from 'teen_process';
+
+import {CHROMEDRIVER_STATES} from '../constants.js';
+import type {ChromedriverCommandContext} from './types.js';
+
+const VERSION_PATTERN = /([\d.]+)/;
+
+/**
+ * Builds command-line arguments for the Chromedriver subprocess.
+ */
+export function buildChromedriverArgs(this: ChromedriverCommandContext): string[] {
+  const args = [`--port=${this.proxyPort}`];
+  if (this.adb?.adbPort) {
+    args.push(`--adb-port=${this.adb.adbPort}`);
+  }
+  if (Array.isArray(this.cmdArgs)) {
+    args.push(...this.cmdArgs);
+  }
+  if (this.logPath) {
+    args.push(`--log-path=${this.logPath}`);
+  }
+  if (this.disableBuildCheck) {
+    args.push('--disable-build-check');
+  }
+  args.push('--verbose');
+  return args;
+}
+
+/**
+ * Retrieves Chromedriver `/status` payload through the active proxy.
+ */
+export async function getStatus(this: ChromedriverCommandContext): Promise<any> {
+  return await this.jwproxy.command('/status', 'GET');
+}
+
+/**
+ * Polls Chromedriver until it reports ready and captures runtime metadata.
+ */
+export async function waitForOnline(this: ChromedriverCommandContext): Promise<void> {
+  const self = this as ChromedriverCommandContext & {
+    getStatus: () => Promise<any>;
+  };
+  let chromedriverStopped = false;
+  await retryInterval(20, 200, async () => {
+    if (this.state === CHROMEDRIVER_STATES.STOPPED) {
+      chromedriverStopped = true;
+      return;
+    }
+    const status = await self.getStatus();
+    if (!util.isPlainObject(status) || !status.ready) {
+      throw new Error(`The response to the /status API is not valid: ${JSON.stringify(status)}`);
+    }
+    const statusPayload = status as Record<string, any>;
+    this._onlineStatus = statusPayload;
+    const versionMatch = VERSION_PATTERN.exec(statusPayload.build?.version ?? '');
+    if (versionMatch) {
+      this._driverVersion = versionMatch[1];
+      this.log.info(`Chromedriver version: ${this._driverVersion}`);
+    } else {
+      this.log.info('Chromedriver version cannot be determined from the /status API response');
+    }
+  });
+  if (chromedriverStopped) {
+    throw new Error('ChromeDriver crashed during startup.');
+  }
+}
+
+/**
+ * Cleans up stale Chromedriver processes and leftover adb forwarded ports.
+ */
+export async function killAll(this: ChromedriverCommandContext): Promise<void> {
+  const cmd = system.isWindows() ? 'wmic' : 'pkill';
+  const args = system.isWindows()
+    ? ['process', 'where', `commandline like '%chromedriver.exe%--port=${this.proxyPort}%'`, 'delete']
+    : ['-15', '-f', `${this.chromedriver}.*--port=${this.proxyPort}`];
+  this.log.debug(`Killing any old chromedrivers, running: ${cmd} ${args.join(' ')}`);
+  try {
+    await exec(cmd, args);
+    this.log.debug('Successfully cleaned up old chromedrivers');
+  } catch {
+    this.log.info('No old chromedrivers seem to exist');
+  }
+
+  if (this.adb) {
+    const udidIndex = this.adb.executable.defaultArgs.findIndex((item: string) => item === '-s');
+    const udid = udidIndex > -1 ? this.adb.executable.defaultArgs[udidIndex + 1] : null;
+    if (udid) {
+      this.log.debug(`Cleaning this device's adb forwarded port socket connections: ${udid}`);
+    } else {
+      this.log.debug(`Cleaning any old adb forwarded port socket connections`);
+    }
+
+    try {
+      for (const conn of await this.adb.getForwardList()) {
+        if (!(conn.includes('webview_devtools') && (!udid || conn.includes(udid)))) {
+          continue;
+        }
+        const params = conn.split(/\s+/);
+        if (params.length > 1) {
+          await this.adb.removePortForward(params[1].replace(/[\D]*/, ''));
+        }
+      }
+    } catch (e) {
+      const err = e as Error;
+      this.log.warn(`Unable to clean forwarded ports. Error: '${err.message}'. Continuing.`);
+    }
+  }
+}

package/node_modules/appium-chromedriver/lib/commands/session.ts

@@ -0,0 +1,105 @@
+import {PROTOCOLS, isStandardCap} from '@appium/base-driver';
+import {util} from '@appium/support';
+import * as semver from 'semver';
+
+import {CHROMEDRIVER_EVENTS, CHROMEDRIVER_STATES} from '../constants.js';
+import {generateLogPrefix} from '../utils.js';
+import type {ChromedriverCommandContext} from './types.js';
+
+const MIN_CD_VERSION_WITH_W3C_SUPPORT = 75;
+const W3C_PREFIX = 'goog:';
+
+export type SessionCapabilities = Record<string, any>;
+
+/**
+ * Converts a capability name to W3C format by adding the 'goog:' prefix if needed.
+ */
+export function toW3cCapName(capName: string): string {
+  return typeof capName === 'string' && !capName.includes(':') && !isStandardCap(capName)
+    ? `${W3C_PREFIX}${capName}`
+    : capName;
+}
+
+/**
+ * Gets a capability value from a capabilities object, handling both standard and W3C format names.
+ */
+export function getCapValue(allCaps: Record<string, any> = {}, rawCapName: string, defaultValue?: any): any {
+  for (const [capName, capValue] of Object.entries(allCaps)) {
+    if (toW3cCapName(capName) === toW3cCapName(rawCapName)) {
+      return capValue;
+    }
+  }
+  return defaultValue;
+}
+
+/**
+ * Converts all capability names in an object to W3C format.
+ */
+export function toW3cCapNames(originalCaps: Record<string, any> = {}): Record<string, any> {
+  return Object.fromEntries(Object.entries(originalCaps).map(([key, value]) => [toW3cCapName(key), value]));
+}
+
+/**
+ * Creates a new Chromedriver session using the negotiated downstream protocol.
+ */
+export async function startSession(this: ChromedriverCommandContext): Promise<SessionCapabilities> {
+  const sessionCaps =
+    this._desiredProtocol === PROTOCOLS.W3C
+      ? {capabilities: {alwaysMatch: toW3cCapNames(this.capabilities)}}
+      : {desiredCapabilities: this.capabilities};
+  this.log.info(
+    `Starting ${this._desiredProtocol} Chromedriver session with capabilities: ` + JSON.stringify(sessionCaps, null, 2),
+  );
+  const response = (await this.jwproxy.command('/session', 'POST', sessionCaps)) as Record<string, any>;
+  this.log.prefix = generateLogPrefix(this, this.jwproxy.sessionId);
+  changeState.call(this, CHROMEDRIVER_STATES.ONLINE);
+  return response?.capabilities ?? response;
+}
+
+/**
+ * Chooses W3C or MJSONWP protocol based on driver/capability constraints.
+ */
+export function syncProtocol(this: ChromedriverCommandContext): keyof typeof PROTOCOLS {
+  if (this.driverVersion) {
+    const coercedVersion = semver.coerce(this.driverVersion);
+    if (!coercedVersion || coercedVersion.major < MIN_CD_VERSION_WITH_W3C_SUPPORT) {
+      this.log.info(
+        `The ChromeDriver v. ${this.driverVersion} does not fully support ${PROTOCOLS.W3C} protocol. ` +
+          `Defaulting to ${PROTOCOLS.MJSONWP}`,
+      );
+      this._desiredProtocol = PROTOCOLS.MJSONWP;
+      return this._desiredProtocol;
+    }
+  }
+
+  const statusMsg = this._onlineStatus?.message;
+  const isOperaDriver = typeof statusMsg === 'string' && statusMsg.includes('OperaDriver');
+  const chromeOptions = getCapValue(this.capabilities, 'chromeOptions');
+  if (util.isPlainObject(chromeOptions) && chromeOptions.w3c === false) {
+    this.log.info(
+      `The ChromeDriver v. ${this.driverVersion} supports ${PROTOCOLS.W3C} protocol, ` +
+        `but ${PROTOCOLS.MJSONWP} one has been explicitly requested`,
+    );
+    this._desiredProtocol = PROTOCOLS.MJSONWP;
+    return this._desiredProtocol;
+  } else if (isOperaDriver) {
+    // OperaDriver requires explicit W3C request or it falls back to JWP.
+    if (util.isPlainObject(chromeOptions)) {
+      chromeOptions.w3c = true;
+    } else {
+      this.capabilities[toW3cCapName('chromeOptions')] = {w3c: true};
+    }
+  }
+
+  this._desiredProtocol = PROTOCOLS.W3C;
+  return this._desiredProtocol;
+}
+
+/**
+ * Updates driver state and emits state-change event payload.
+ */
+export function changeState(this: ChromedriverCommandContext, state: string): void {
+  this.state = state;
+  this.log.debug(`Changed state to '${state}'`);
+  this.emit(CHROMEDRIVER_EVENTS.CHANGED, {state});
+}

package/node_modules/appium-chromedriver/lib/commands/types.ts

@@ -0,0 +1,36 @@
+import type {EventEmitter} from 'node:events';
+
+// `keyof typeof PROTOCOLS` requires the runtime `PROTOCOLS` binding (not `import type`).
+// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- see above
+import {PROTOCOLS, type WebDriverProxy} from '@appium/base-driver';
+import type {AppiumLogger} from '@appium/types';
+import type * as TeenProcess from 'teen_process';
+
+import type {ChromedriverStorageClient} from '../storage-client/storage-client.js';
+import type {ChromedriverAdb, ChromedriverOpts} from '../types.js';
+
+export interface ChromedriverCommandContext extends EventEmitter {
+  state: string;
+  proxyPort: number;
+  adb?: ChromedriverAdb;
+  cmdArgs?: string[];
+  logPath?: string;
+  disableBuildCheck: boolean;
+  mappingPath?: string;
+  executableDir: string;
+  isCustomExecutableDir: boolean;
+  useSystemExecutable: boolean;
+  chromedriver?: string;
+  executableVerified: boolean;
+  bundleId?: string;
+  details?: ChromedriverOpts['details'];
+  storageClient: ChromedriverStorageClient | null;
+  _execFunc: typeof TeenProcess.exec;
+  _driverVersion: string | null;
+  _onlineStatus: Record<string, any> | null;
+  _desiredProtocol: keyof typeof PROTOCOLS | null;
+  capabilities: Record<string, any>;
+  jwproxy: WebDriverProxy;
+  log: AppiumLogger;
+  driverVersion: string | null;
+}