tabwright 1.0.0

package/src/browser-config.ts

@@ -0,0 +1,179 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { chromium } from '@xmorse/playwright-core'
+import { findInstalledChrome } from './browser-install.js'
+// NOTE: browser-config uses chromium synchronously (executablePath) during browser start.
+// Patchright mode only affects connectOverCDP in executor.ts, not browser binary lookup.
+
+type BrowserLookupOptions = {
+  browserPath?: string
+  env?: NodeJS.ProcessEnv
+  platform?: NodeJS.Platform
+  homeDir?: string
+  existsSync?: (filePath: string) => boolean
+}
+
+function expandHomeDirectory({ filePath, homeDir }: { filePath: string; homeDir: string }): string {
+  if (!filePath.startsWith('~/')) {
+    return filePath
+  }
+  return path.join(homeDir, filePath.slice(2))
+}
+
+function dedupePaths(pathsToCheck: string[]): string[] {
+  return Array.from(new Set(pathsToCheck))
+}
+
+function getPlaywrightChromiumCandidate(): string[] {
+  const executablePath = chromium.executablePath()
+  if (!executablePath) {
+    return []
+  }
+  return [executablePath]
+}
+
+function getPathEntries(env: NodeJS.ProcessEnv): string[] {
+  const rawPath = env.PATH || env.Path || ''
+  return rawPath
+    .split(path.delimiter)
+    .filter(Boolean)
+    .map((entry) => {
+      return entry.trim()
+    })
+}
+
+function getExecutableNames(platform: NodeJS.Platform): string[] {
+  if (platform === 'win32') {
+    return ['chrome.exe', 'chromium.exe']
+  }
+  return ['chrome', 'chromium', 'chromium-browser']
+}
+
+function getPathExecutableCandidates({
+  platform,
+  env,
+}: {
+  platform: NodeJS.Platform
+  env: NodeJS.ProcessEnv
+}): string[] {
+  const executableNames = getExecutableNames(platform)
+  return getPathEntries(env).flatMap((entry) => {
+    return executableNames.map((name) => {
+      return path.join(entry, name)
+    })
+  })
+}
+
+export function getBrowserExecutableCandidates({
+  platform = os.platform(),
+  env = process.env,
+  homeDir = os.homedir(),
+}: Omit<BrowserLookupOptions, 'browserPath' | 'existsSync'> = {}): string[] {
+  const platformCandidates = (() => {
+    if (platform === 'darwin') {
+      return [
+        '/Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+        '~/Applications/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+        '/Applications/Chromium.app/Contents/MacOS/Chromium',
+        '~/Applications/Chromium.app/Contents/MacOS/Chromium',
+      ]
+    }
+
+    if (platform === 'win32') {
+      const localAppData = env.LOCALAPPDATA || ''
+      const programFiles = env.PROGRAMFILES || 'C:\\Program Files'
+      const programFilesX86 = env['PROGRAMFILES(X86)'] || 'C:\\Program Files (x86)'
+
+      return [
+        path.join(programFiles, 'Google', 'Chrome for Testing', 'Application', 'chrome.exe'),
+        path.join(programFilesX86, 'Google', 'Chrome for Testing', 'Application', 'chrome.exe'),
+        path.join(localAppData, 'Google', 'Chrome for Testing', 'Application', 'chrome.exe'),
+        path.join(programFiles, 'Chromium', 'Application', 'chromium.exe'),
+        path.join(programFilesX86, 'Chromium', 'Application', 'chromium.exe'),
+        path.join(localAppData, 'Chromium', 'Application', 'chromium.exe'),
+      ]
+    }
+
+    return [
+      '/opt/google/chrome-for-testing/chrome',
+      '/usr/local/bin/chrome',
+      '/usr/bin/chrome',
+      '/usr/bin/chromium',
+      '/usr/bin/chromium-browser',
+      '/snap/bin/chromium',
+    ]
+  })()
+
+  const pathCandidates = getPathExecutableCandidates({ platform, env })
+  return dedupePaths(
+    [...platformCandidates, ...pathCandidates, ...getPlaywrightChromiumCandidate()].map((filePath) => {
+      return expandHomeDirectory({ filePath, homeDir })
+    }),
+  )
+}
+
+export function resolveBrowserExecutablePath({
+  browserPath,
+  env = process.env,
+  platform = os.platform(),
+  homeDir = os.homedir(),
+  existsSync = fs.existsSync,
+}: BrowserLookupOptions = {}): string {
+  const explicitPath = browserPath?.trim()
+  if (explicitPath) {
+    const resolvedExplicitPath = expandHomeDirectory({ filePath: explicitPath, homeDir })
+    if (!existsSync(resolvedExplicitPath)) {
+      throw new Error(`Browser binary not found at: ${resolvedExplicitPath}`)
+    }
+    return resolvedExplicitPath
+  }
+
+  const envPath = env.TABWRIGHT_BROWSER_PATH?.trim() || env.PLAYWRITER_BROWSER_PATH?.trim()
+  if (envPath) {
+    const resolvedEnvPath = expandHomeDirectory({ filePath: envPath, homeDir })
+    if (!existsSync(resolvedEnvPath)) {
+      throw new Error(`TABWRIGHT_BROWSER_PATH does not exist: ${resolvedEnvPath}`)
+    }
+    return resolvedEnvPath
+  }
+
+  // Check Chrome downloaded by `tabwright browser install` first (highest priority)
+  const installedChrome = findInstalledChrome()
+  if (installedChrome) {
+    return installedChrome
+  }
+
+  const candidates = getBrowserExecutableCandidates({ platform, env, homeDir })
+  const resolvedPath = candidates.find((candidate) => {
+    return existsSync(candidate)
+  })
+
+  if (resolvedPath) {
+    return resolvedPath
+  }
+
+  const searchedPathsText = candidates.map((candidate) => {
+    return `- ${candidate}`
+  })
+
+  throw new Error(
+    'Could not find a supported browser binary. Run `tabwright browser install` to download Chrome for Testing, or pass a binary path.' +
+      `\n\nSearched paths:\n- ~/.tabwright/browsers/ (tabwright browser install)\n${searchedPathsText.join('\n')}`,
+  )
+}
+
+export function shouldUseHeadlessByDefault({
+  platform = os.platform(),
+  env = process.env,
+}: Omit<BrowserLookupOptions, 'browserPath' | 'homeDir' | 'existsSync'> = {}): boolean {
+  if (platform !== 'linux') {
+    return false
+  }
+
+  return !env.DISPLAY && !env.WAYLAND_DISPLAY
+}
+
+export function getBrowserExecutablePath(browserPath?: string): string {
+  return resolveBrowserExecutablePath({ browserPath })
+}

package/src/browser-install.ts

@@ -0,0 +1,284 @@
+/**
+ * Download and install Chrome for Testing into ~/.tabwright/browsers/.
+ * Similar to agent-browser's install command: fetches the latest stable
+ * Chrome for Testing build from Google's official automation channel.
+ */
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { pipeline } from 'node:stream/promises'
+import { Readable } from 'node:stream'
+import { execFileSync } from 'node:child_process'
+import { getTabwrightUserDataDir } from './product-paths.js'
+
+const LAST_KNOWN_GOOD_URL =
+  'https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json'
+
+export function getBrowsersDir(): string {
+  return path.join(getTabwrightUserDataDir(), 'browsers')
+}
+
+function getPlatformKey(): string {
+  const platform = os.platform()
+  const arch = os.arch()
+  if (platform === 'darwin' && arch === 'arm64') {
+    return 'mac-arm64'
+  }
+  if (platform === 'darwin' && arch === 'x64') {
+    return 'mac-x64'
+  }
+  if (platform === 'linux' && arch === 'x64') {
+    return 'linux64'
+  }
+  if (platform === 'win32' && arch === 'x64') {
+    return 'win64'
+  }
+  throw new Error(
+    `Unsupported platform for Chrome for Testing download: ${platform}/${arch}. ` +
+      `Install Chromium manually and use TABWRIGHT_BROWSER_PATH to point to it.`,
+  )
+}
+
+/**
+ * Find the Chrome binary inside a downloaded Chrome for Testing directory.
+ */
+function findChromeBinaryInDir(dir: string): string | null {
+  const platform = os.platform()
+
+  if (platform === 'darwin') {
+    const candidates = [
+      path.join(dir, 'Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing'),
+      path.join(dir, `chrome-${getPlatformKey()}/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing`),
+    ]
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) {
+        return candidate
+      }
+    }
+  }
+
+  if (platform === 'linux') {
+    const candidates = [
+      path.join(dir, 'chrome'),
+      path.join(dir, 'chrome-linux64/chrome'),
+    ]
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) {
+        return candidate
+      }
+    }
+  }
+
+  if (platform === 'win32') {
+    const candidates = [
+      path.join(dir, 'chrome.exe'),
+      path.join(dir, 'chrome-win64/chrome.exe'),
+    ]
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) {
+        return candidate
+      }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Find Chrome installed by `tabwright browser install` in ~/.tabwright/browsers/.
+ * Returns the path to the Chrome binary, or null if not found.
+ */
+export function findInstalledChrome(): string | null {
+  const browsersDir = getBrowsersDir()
+  if (!fs.existsSync(browsersDir)) {
+    return null
+  }
+
+  const entries = fs.readdirSync(browsersDir, { withFileTypes: true })
+    .filter((e) => {
+      return e.isDirectory() && e.name.startsWith('chrome-')
+    })
+    .sort((a, b) => {
+      // Sort descending so newest version is first
+      return b.name.localeCompare(a.name)
+    })
+
+  for (const entry of entries) {
+    const dir = path.join(browsersDir, entry.name)
+    const binary = findChromeBinaryInDir(dir)
+    if (binary) {
+      return binary
+    }
+  }
+
+  return null
+}
+
+interface VersionInfo {
+  version: string
+  downloadUrl: string
+}
+
+async function fetchDownloadUrl(): Promise<VersionInfo> {
+  const response = await fetch(LAST_KNOWN_GOOD_URL, {
+    signal: AbortSignal.timeout(30000),
+  })
+  if (!response.ok) {
+    throw new Error(`Failed to fetch Chrome version info: HTTP ${response.status}`)
+  }
+
+  const data = (await response.json()) as {
+    channels: {
+      Stable: {
+        version: string
+        downloads: {
+          chrome: Array<{ platform: string; url: string }>
+        }
+      }
+    }
+  }
+
+  const channel = data.channels?.Stable
+  if (!channel) {
+    throw new Error('No Stable channel found in Chrome for Testing version info')
+  }
+
+  const platformKey = getPlatformKey()
+  const download = channel.downloads?.chrome?.find((d) => {
+    return d.platform === platformKey
+  })
+  if (!download) {
+    throw new Error(`No Chrome for Testing download found for platform: ${platformKey}`)
+  }
+
+  return { version: channel.version, downloadUrl: download.url }
+}
+
+async function downloadFile(url: string, destPath: string): Promise<void> {
+  // 5-minute timeout per attempt, 3 retries for transient errors
+  const maxAttempts = 3
+  let lastError: Error | null = null
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      await downloadFileAttempt(url, destPath)
+      return
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error))
+      // Don't retry on 4xx (permanent errors)
+      if (lastError.message.includes('HTTP 4')) {
+        throw lastError
+      }
+      if (attempt < maxAttempts) {
+        const delay = attempt * 2000
+        console.log(`  Download attempt ${attempt} failed, retrying in ${delay / 1000}s...`)
+        await new Promise((resolve) => {
+          return setTimeout(resolve, delay)
+        })
+      }
+    }
+  }
+  throw lastError!
+}
+
+async function downloadFileAttempt(url: string, destPath: string): Promise<void> {
+  const response = await fetch(url, {
+    signal: AbortSignal.timeout(300_000), // 5 minute timeout
+  })
+  if (!response.ok) {
+    throw new Error(`Download failed: HTTP ${response.status} for ${url}`)
+  }
+  if (!response.body) {
+    throw new Error('Download failed: no response body')
+  }
+
+  const totalBytes = Number(response.headers.get('content-length') || 0)
+  let downloadedBytes = 0
+  let lastPct = 0
+
+  const progressStream = new TransformStream({
+    transform(chunk, controller) {
+      downloadedBytes += chunk.byteLength
+      if (totalBytes > 0) {
+        const pct = Math.floor((downloadedBytes / totalBytes) * 100)
+        if (pct >= lastPct + 5) {
+          lastPct = pct
+          const mb = (downloadedBytes / 1_048_576).toFixed(0)
+          const totalMb = (totalBytes / 1_048_576).toFixed(0)
+          process.stderr.write(`\r  ${mb}/${totalMb} MB (${pct}%)`)
+        }
+      }
+      controller.enqueue(chunk)
+    },
+  })
+
+  const readableStream = response.body.pipeThrough(progressStream)
+  const nodeReadable = Readable.fromWeb(readableStream as any)
+  const writeStream = fs.createWriteStream(destPath)
+  await pipeline(nodeReadable, writeStream)
+  process.stderr.write('\n')
+}
+
+function extractZip(zipPath: string, destDir: string): void {
+  fs.mkdirSync(destDir, { recursive: true })
+  const platform = os.platform()
+
+  if (platform === 'win32') {
+    execFileSync('powershell', [
+      '-Command',
+      `Expand-Archive -Path '${zipPath}' -DestinationPath '${destDir}' -Force`,
+    ], { stdio: 'pipe' })
+  } else {
+    execFileSync('unzip', ['-o', '-q', zipPath, '-d', destDir], { stdio: 'pipe' })
+  }
+}
+
+export async function installChrome(): Promise<{ version: string; binaryPath: string }> {
+  console.log('Fetching latest Chrome for Testing version...')
+  const { version, downloadUrl } = await fetchDownloadUrl()
+
+  const browsersDir = getBrowsersDir()
+  const destDir = path.join(browsersDir, `chrome-${version}`)
+
+  // Check if already installed
+  const existingBinary = findChromeBinaryInDir(destDir)
+  if (existingBinary) {
+    console.log(`Chrome ${version} is already installed.`)
+    console.log(`  Location: ${existingBinary}`)
+    return { version, binaryPath: existingBinary }
+  }
+
+  console.log(`Downloading Chrome ${version} for ${getPlatformKey()}...`)
+  console.log(`  ${downloadUrl}`)
+
+  const tmpZip = path.join(os.tmpdir(), `tabwright-chrome-${version}.zip`)
+  try {
+    await downloadFile(downloadUrl, tmpZip)
+    console.log('Extracting...')
+    extractZip(tmpZip, destDir)
+  } finally {
+    // Clean up temp zip
+    try {
+      fs.unlinkSync(tmpZip)
+    } catch {
+      // ignore cleanup errors
+    }
+  }
+
+  const binaryPath = findChromeBinaryInDir(destDir)
+  if (!binaryPath) {
+    // Clean up failed extraction
+    fs.rmSync(destDir, { recursive: true, force: true })
+    throw new Error('Chrome was downloaded but the binary could not be found in the extracted archive.')
+  }
+
+  // Ensure binary is executable on Unix
+  if (os.platform() !== 'win32') {
+    fs.chmodSync(binaryPath, 0o755)
+  }
+
+  console.log(`Chrome ${version} installed successfully.`)
+  console.log(`  Location: ${binaryPath}`)
+  return { version, binaryPath }
+}

package/src/browser-launch.ts

@@ -0,0 +1,75 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+import { EXTENSION_IDS } from './utils.js'
+import { getTabwrightUserDataDir } from './product-paths.js'
+
+export type BrowserLaunchOptions = {
+  extensionPath: string
+  userDataDir: string
+  headless: boolean
+  noSandbox?: boolean
+  url?: string
+}
+
+export function getDefaultBrowserUserDataDir(): string {
+  return path.join(getTabwrightUserDataDir(), 'browser-profile')
+}
+
+export function getBrowserLaunchArgs({
+  extensionPath,
+  userDataDir,
+  headless,
+  noSandbox = false,
+  url = 'about:blank',
+}: BrowserLaunchOptions): string[] {
+  const recordingFlags = EXTENSION_IDS.map((extensionId) => {
+    return `--allowlisted-extension-id=${extensionId}`
+  })
+
+  const args = [
+    `--user-data-dir=${path.resolve(userDataDir)}`,
+    '--profile-directory=Default',
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--auto-accept-this-tab-capture',
+    ...recordingFlags,
+    `--disable-extensions-except=${path.resolve(extensionPath)}`,
+    `--load-extension=${path.resolve(extensionPath)}`,
+  ]
+
+  if (headless) {
+    args.push('--headless=new')
+  }
+
+  if (noSandbox) {
+    args.push('--no-sandbox', '--disable-setuid-sandbox')
+  }
+
+  args.push(url)
+  return args
+}
+
+export function startBrowserProcess({
+  browserPath,
+  args,
+  userDataDir,
+}: {
+  browserPath: string
+  args: string[]
+  userDataDir: string
+}): { pid: number } {
+  fs.mkdirSync(path.resolve(userDataDir), { recursive: true })
+
+  const browserProcess = spawn(browserPath, args, {
+    detached: true,
+    stdio: 'ignore',
+  })
+  browserProcess.unref()
+
+  if (!browserProcess.pid) {
+    throw new Error(`Failed to start browser process for ${browserPath}`)
+  }
+
+  return { pid: browserProcess.pid }
+}