tabwright 1.0.0 → 1.0.1

package/src/relay-client.ts

@@ -1,572 +0,0 @@
-/**
- * Shared utilities for connecting to the relay server.
- * Used by both MCP and CLI.
- */
-
-import { spawn } from 'node:child_process'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-import pc from 'picocolors'
-import { getListeningPidsForPort, killPortProcess } from './kill-port.js'
-import { RELAY_FEATURES } from './protocol.js'
-import { VERSION, sleep, LOG_FILE_PATH } from './utils.js'
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = path.dirname(__filename)
-
-export const RELAY_PORT = Number(process.env.TABWRIGHT_PORT || process.env.PLAYWRITER_PORT) || 19988
-export const LOCAL_RELAY_HOSTS = ['127.0.0.1', 'localhost', '[::1]'] as const
-
-export type ExtensionStatus = {
-  extensionId: string
-  stableKey?: string
-  browser: string | null
-  profile: { email: string; id: string } | null
-  activeTargets: number
-  playwriterVersion: string | null
-  protocolVersion?: number
-  features?: string[]
-  connectionHealth?: 'ready' | 'limited' | 'legacy'
-  missingFeatures?: string[]
-}
-
-/**
- * Select an extension only when the choice is unambiguous.
- * A single connection remains the backward-compatible default. With multiple
- * connections, an enabled tab is a useful signal only when exactly one
- * extension has one.
- */
-export function selectImplicitExtension(extensions: ExtensionStatus[]): ExtensionStatus | null {
-  if (extensions.length === 1) {
-    return extensions[0]!
-  }
-
-  const activeExtensions = extensions.filter((extension) => {
-    return extension.activeTargets > 0
-  })
-  if (activeExtensions.length === 1) {
-    return activeExtensions[0]!
-  }
-
-  return null
-}
-
-export function getLocalRelayHttpBaseUrls(port: number = RELAY_PORT): string[] {
-  return LOCAL_RELAY_HOSTS.map((host) => {
-    return `http://${host}:${port}`
-  })
-}
-
-async function fetchLocalRelayPath({
-  path,
-  port = RELAY_PORT,
-  timeoutMs = 2000,
-  init,
-  accept = () => {
-    return true
-  },
-}: {
-  path: string
-  port?: number
-  timeoutMs?: number
-  init?: RequestInit
-  accept?: (response: Response) => boolean
-}): Promise<{ response: Response; httpBaseUrl: string } | null> {
-  const attempts = getLocalRelayHttpBaseUrls(port)
-
-  for (const httpBaseUrl of attempts) {
-    try {
-      const response = await fetch(`${httpBaseUrl}${path}`, {
-        ...init,
-        signal: AbortSignal.timeout(timeoutMs),
-      })
-      if (accept(response)) {
-        return { response, httpBaseUrl }
-      }
-    } catch {}
-  }
-
-  return null
-}
-
-export async function getLocalRelayHttpBaseUrl(port: number = RELAY_PORT): Promise<string> {
-  const result = await fetchLocalRelayPath({
-    path: '/version',
-    port,
-    timeoutMs: 500,
-    accept: (response) => {
-      return response.ok
-    },
-  })
-  if (result) {
-    return result.httpBaseUrl
-  }
-  return getLocalRelayHttpBaseUrls(port)[0]!
-}
-
-export async function getRelayServerVersion(port: number = RELAY_PORT): Promise<string | null> {
-  const result = await fetchLocalRelayPath({
-    path: '/version',
-    port,
-    timeoutMs: 2000,
-    accept: (response) => {
-      return response.ok
-    },
-  })
-  if (!result) {
-    return null
-  }
-  const data = (await result.response.json()) as { version: string }
-  return data.version
-}
-
-export async function getRelayServerFeatures(port: number = RELAY_PORT): Promise<string[] | null> {
-  const result = await fetchLocalRelayPath({
-    path: '/features',
-    port,
-    timeoutMs: 2000,
-    accept: (response) => {
-      return response.ok
-    },
-  })
-  if (!result) {
-    return null
-  }
-  const data: unknown = await result.response.json()
-  if (!data || typeof data !== 'object') {
-    return null
-  }
-  const features = (data as { features?: unknown }).features
-  if (!Array.isArray(features) || !features.every((feature) => typeof feature === 'string')) {
-    return null
-  }
-  return features
-}
-
-export function supportsRelayFeatures(options: {
-  features: readonly string[] | null
-  requiredFeatures?: readonly string[]
-}): boolean {
-  const requiredFeatures = options.requiredFeatures || RELAY_FEATURES
-  const features = options.features
-  if (!features) {
-    return false
-  }
-  return requiredFeatures.every((feature) => {
-    return features.includes(feature)
-  })
-}
-
-function acceptsRelayVersion({
-  version,
-  expectedVersion,
-  minimumVersion,
-}: {
-  version: string | null
-  expectedVersion?: string
-  minimumVersion?: string
-}): boolean {
-  if (!version) {
-    return false
-  }
-  if (expectedVersion) {
-    return version === expectedVersion
-  }
-  if (minimumVersion) {
-    return compareVersions(version, minimumVersion) >= 0
-  }
-  return true
-}
-
-/**
- * Poll /version until a relay responds or timeout expires.
- * Used during startup races where a relay may have bound the port
- * but isn't serving HTTP yet (issue #75).
- */
-export async function waitForRelayVersion({
-  port = RELAY_PORT,
-  timeoutMs = 2000,
-  intervalMs = 200,
-  expectedVersion,
-  minimumVersion,
-}: {
-  port?: number
-  timeoutMs?: number
-  intervalMs?: number
-  /** Keep polling until this exact relay version responds. Takes precedence over minimumVersion. */
-  expectedVersion?: string
-  /** Keep polling until this relay version or a newer one responds. */
-  minimumVersion?: string
-} = {}): Promise<string | null> {
-  const end = Date.now() + timeoutMs
-  while (Date.now() < end) {
-    const version = await getRelayServerVersion(port)
-    if (acceptsRelayVersion({ version, expectedVersion, minimumVersion })) {
-      return version
-    }
-    await sleep(intervalMs)
-  }
-  return null
-}
-
-async function waitForCurrentRelayReadiness(options: {
-  port: number
-  timeoutMs: number
-  intervalMs?: number
-}): Promise<string | null> {
-  const end = Date.now() + options.timeoutMs
-  const intervalMs = options.intervalMs || 200
-  while (Date.now() < end) {
-    const version = await getRelayServerVersion(options.port)
-    if (version && compareVersions(version, VERSION) > 0) {
-      return version
-    }
-    if (version === VERSION) {
-      const features = await getRelayServerFeatures(options.port)
-      if (supportsRelayFeatures({ features })) {
-        return version
-      }
-    }
-    await sleep(intervalMs)
-  }
-  return null
-}
-
-export async function getExtensionStatus(port: number = RELAY_PORT): Promise<{
-  connected: boolean
-  activeTargets: number
-  playwriterVersion: string | null
-  protocolVersion?: number
-  features?: string[]
-  connectionHealth?: 'ready' | 'limited' | 'legacy'
-  missingFeatures?: string[]
-} | null> {
-  const result = await fetchLocalRelayPath({
-    path: '/extension/status',
-    port,
-    timeoutMs: 500,
-    accept: (response) => {
-      return response.ok
-    },
-  })
-  if (!result) {
-    return null
-  }
-  return (await result.response.json()) as {
-    connected: boolean
-    activeTargets: number
-    playwriterVersion: string | null
-    protocolVersion?: number
-    features?: string[]
-    connectionHealth?: 'ready' | 'limited' | 'legacy'
-    missingFeatures?: string[]
-  }
-}
-
-export async function getExtensionsStatus(port: number = RELAY_PORT): Promise<ExtensionStatus[]> {
-  const result = await fetchLocalRelayPath({
-    path: '/extensions/status',
-    port,
-    timeoutMs: 2000,
-    accept: (response) => {
-      return response.ok
-    },
-  })
-  if (result) {
-    const data = (await result.response.json()) as {
-      extensions: ExtensionStatus[]
-    }
-    return data.extensions || []
-  }
-
-  const fallbackResult = await fetchLocalRelayPath({
-    path: '/extension/status',
-    port,
-    timeoutMs: 2000,
-    accept: (response) => {
-      return response.ok
-    },
-  })
-  if (!fallbackResult) {
-    return []
-  }
-
-  const fallbackData = (await fallbackResult.response.json()) as {
-    connected: boolean
-    activeTargets: number
-    browser: string | null
-    profile: { email: string; id: string } | null
-    playwriterVersion?: string | null
-    protocolVersion?: number
-    features?: string[]
-    connectionHealth?: 'ready' | 'limited' | 'legacy'
-    missingFeatures?: string[]
-  }
-
-  if (!fallbackData?.connected) {
-    return []
-  }
-
-  return [
-    {
-      extensionId: 'default',
-      stableKey: undefined,
-      browser: fallbackData.browser,
-      profile: fallbackData.profile,
-      activeTargets: fallbackData.activeTargets,
-      playwriterVersion: fallbackData.playwriterVersion || null,
-      protocolVersion: fallbackData.protocolVersion,
-      features: fallbackData.features,
-      connectionHealth: fallbackData.connectionHealth,
-      missingFeatures: fallbackData.missingFeatures,
-    },
-  ]
-}
-
-function getExtensionSettleSignature(extensions: ExtensionStatus[]): string {
-  return extensions
-    .map((extension) => {
-      return JSON.stringify({
-        extensionId: extension.extensionId,
-        stableKey: extension.stableKey ?? null,
-        activeTargets: extension.activeTargets,
-      })
-    })
-    .sort()
-    .join('\n')
-}
-
-/**
- * Wait for at least one extension to appear in extensions status.
- * Returns connected extension entries, or [] on timeout.
- */
-export async function waitForConnectedExtensions(
-  options: {
-    port?: number
-    timeoutMs?: number
-    pollIntervalMs?: number
-    /** Wait for the connection snapshot to remain unchanged before returning. Default: 0. */
-    settleMs?: number
-    logger?: { log: (...args: any[]) => void }
-  } = {},
-): Promise<ExtensionStatus[]> {
-  const { port = RELAY_PORT, timeoutMs = 5000, pollIntervalMs = 200, settleMs = 0, logger } = options
-  const startTime = Date.now()
-  let latestNonEmpty: ExtensionStatus[] = []
-  let latestSnapshotWasConnected = false
-  let stableSignature: string | null = null
-  let stableSince = 0
-
-  logger?.log(pc.dim('Waiting for extension to connect...'))
-
-  while (Date.now() - startTime < timeoutMs) {
-    const extensions = await getExtensionsStatus(port)
-    if (extensions.length > 0) {
-      latestSnapshotWasConnected = true
-      latestNonEmpty = extensions
-      const signature = getExtensionSettleSignature(extensions)
-      if (signature !== stableSignature) {
-        stableSignature = signature
-        stableSince = Date.now()
-      }
-      if (settleMs === 0 || Date.now() - stableSince >= settleMs) {
-        logger?.log(pc.green('Extension connected'))
-        return latestNonEmpty
-      }
-    } else if (latestNonEmpty.length > 0) {
-      latestSnapshotWasConnected = false
-      stableSignature = null
-    }
-    await sleep(pollIntervalMs)
-  }
-
-  if (latestSnapshotWasConnected && latestNonEmpty.length > 0) {
-    logger?.log(pc.green('Extension connected'))
-    return latestNonEmpty
-  }
-
-  logger?.log(pc.yellow('Extension did not connect within timeout'))
-  return []
-}
-
-async function killRelayServer(options: { port: number; waitForFreeMs?: number }): Promise<void> {
-  const { port, waitForFreeMs = 3000 } = options
-
-  try {
-    await killPortProcess({ port })
-  } catch {
-    return
-  }
-
-  const startTime = Date.now()
-  while (Date.now() - startTime < waitForFreeMs) {
-    const pids = await getListeningPidsForPort({ port }).catch(() => [])
-    if (pids.length === 0) {
-      return
-    }
-    await sleep(100)
-  }
-}
-
-/**
- * Compare two semver versions. Returns:
- * - negative if v1 < v2
- * - 0 if v1 === v2
- * - positive if v1 > v2
- */
-export function compareVersions(v1: string, v2: string): number {
-  const parts1 = v1.split('.').map(Number)
-  const parts2 = v2.split('.').map(Number)
-  const len = Math.max(parts1.length, parts2.length)
-
-  for (let i = 0; i < len; i++) {
-    const p1 = parts1[i] || 0
-    const p2 = parts2[i] || 0
-    if (p1 !== p2) {
-      return p1 - p2
-    }
-  }
-  return 0
-}
-
-/**
- * Check if the running Tabwright package is older than the version the extension was built with.
- * The extension bundles the Tabwright version at build time. If the extension reports a newer
- * version, it means the user's CLI/MCP needs updating.
- * Returns a warning message if outdated, null otherwise.
- */
-export function getExtensionOutdatedWarning(extensionTabwrightVersion: string | null | undefined): string | null {
-  if (!extensionTabwrightVersion) {
-    return null
-  }
-  if (compareVersions(extensionTabwrightVersion, VERSION) > 0) {
-    return `Tabwright ${VERSION} is outdated (extension requires ${extensionTabwrightVersion}). Run \`npm install -g tabwright@latest\` or update the tabwright package in your project.`
-  }
-  return null
-}
-
-export interface EnsureRelayServerOptions {
-  logger?: { log: (...args: any[]) => void }
-  /** If true, will kill and restart server on version mismatch. Default: true */
-  restartOnVersionMismatch?: boolean
-  /** Pass additional environment variables to the relay server process */
-  env?: Record<string, string>
-}
-
-// Module-level dedup: if ensureRelayServer is called concurrently within the
-// same process (e.g. two MCP tool handlers at once), only one spawn runs.
-let pendingEnsure: Promise<true | undefined> | null = null
-
-/**
- * Ensures the relay server is running. Starts it if not running.
- * Optionally restarts on version mismatch.
- * Concurrent calls within the same process are deduplicated.
- */
-export async function ensureRelayServer(options: EnsureRelayServerOptions = {}): Promise<true | undefined> {
-  if (pendingEnsure) {
-    return pendingEnsure
-  }
-  pendingEnsure = ensureRelayServerImpl(options).finally(() => {
-    pendingEnsure = null
-  })
-  return pendingEnsure
-}
-
-async function ensureRelayServerImpl(options: EnsureRelayServerOptions = {}): Promise<true | undefined> {
-  const { logger, restartOnVersionMismatch = true, env: additionalEnv } = options
-  const serverVersion = await getRelayServerVersion(RELAY_PORT)
-  const sameVersionFeatures = serverVersion === VERSION ? await getRelayServerFeatures(RELAY_PORT) : null
-
-  if (serverVersion === VERSION && supportsRelayFeatures({ features: sameVersionFeatures })) {
-    return
-  }
-
-  // Don't restart if server version is higher than our version.
-  // This prevents older clients from killing a newer server.
-  if (serverVersion !== null && compareVersions(serverVersion, VERSION) > 0) {
-    return
-  }
-
-  if (serverVersion !== null) {
-    if (restartOnVersionMismatch) {
-      const reason =
-        serverVersion === VERSION
-          ? `CDP relay server is missing current features (${RELAY_FEATURES.join(', ')}), restarting...`
-          : `CDP relay server version mismatch (server: ${serverVersion}, client: ${VERSION}), restarting...`
-      logger?.log(pc.yellow(reason))
-      await killRelayServer({ port: RELAY_PORT })
-    } else {
-      // Server is running but different version, just use it
-      return
-    }
-  } else {
-    const listeningPids = await getListeningPidsForPort({ port: RELAY_PORT }).catch(() => [])
-    if (listeningPids.length > 0) {
-      // Something is on the port but /version didn't respond. It might be a
-      // relay that's still starting (race with another CLI/MCP instance).
-      // Poll /version briefly before deciding to kill it (issue #75).
-      const foundVersion = await waitForRelayVersion({ port: RELAY_PORT })
-      if (foundVersion) {
-        // A relay came up while we waited; only reuse the current version when
-        // it also exposes the feature contract expected by this build.
-        if (compareVersions(foundVersion, VERSION) > 0) {
-          return
-        }
-        if (foundVersion === VERSION) {
-          const features = await getRelayServerFeatures(RELAY_PORT)
-          if (supportsRelayFeatures({ features })) {
-            return
-          }
-        }
-        if (!restartOnVersionMismatch) {
-          return
-        }
-        const reason =
-          foundVersion === VERSION
-            ? `CDP relay server is missing current features (${RELAY_FEATURES.join(', ')}), restarting...`
-            : `CDP relay server version mismatch (server: ${foundVersion}, client: ${VERSION}), restarting...`
-        logger?.log(pc.yellow(reason))
-      } else {
-        logger?.log(
-          pc.yellow(
-            `Port ${RELAY_PORT} is already in use (pid(s): ${listeningPids.join(', ')}). Attempting to stop the existing process...`,
-          ),
-        )
-      }
-      await killRelayServer({ port: RELAY_PORT })
-    }
-
-    logger?.log(pc.dim('CDP relay server not running, starting it...'))
-  }
-
-  // Detect if we're running from source (.ts) or compiled (.js)
-  // This handles: tsx, vite-node, ts-node, or direct node on compiled output
-  const isRunningFromSource = __filename.endsWith('.ts')
-  const scriptPath = isRunningFromSource
-    ? path.resolve(__dirname, './start-relay-server.ts')
-    : path.resolve(__dirname, './start-relay-server.js')
-
-  const serverProcess = spawn(isRunningFromSource ? 'tsx' : process.execPath, [scriptPath], {
-    detached: true,
-    stdio: 'ignore',
-    env: { ...process.env, ...additionalEnv },
-  })
-
-  serverProcess.unref()
-
-  const startTimeoutMs = 5000
-  const startTime = Date.now()
-
-  const newVersion = await waitForCurrentRelayReadiness({
-    port: RELAY_PORT,
-    timeoutMs: startTimeoutMs,
-  })
-  if (newVersion && compareVersions(newVersion, VERSION) >= 0) {
-    logger?.log(pc.green('CDP relay server started successfully'))
-    await sleep(1000)
-    return true
-  }
-
-  const waitedMs = Date.now() - startTime
-  throw new Error(`Failed to start CDP relay server within ${waitedMs}ms. Check logs at: ${LOG_FILE_PATH}`)
-}