tabwright 1.0.0

package/src/cloud-client.ts

@@ -0,0 +1,179 @@
+// HTTP client for CLI to call the website's /api/cloud/* routes.
+// Auth: three methods, checked in priority order:
+//   1. TABWRIGHT_API_KEY env var → sent as x-api-key header (for CI/VPS/headless)
+//   2. TABWRIGHT_CLOUD_TOKEN env var → sent as Authorization: Bearer (for CI with session tokens)
+//   3. ~/.tabwright/auth.json file → saved by `cloud login` device flow
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { getTabwrightUserDataDir } from './product-paths.js'
+
+const DEFAULT_BASE_URL = 'https://playwriter.dev'
+const AUTH_FILE = path.join(getTabwrightUserDataDir(), 'auth.json')
+
+/** Build the hosted live-view URL from the exact CDP WebSocket URL.
+ *  Passes the full wss endpoint as ?wss= param so the client connects
+ *  to the exact host (Browser Use can shard across cdp1, cdp2, etc.). */
+export function buildLiveUrl(cdpUrl: string, baseUrl: string = DEFAULT_BASE_URL): string {
+  // Browser Use returns https:// CDP URLs; the live viewer needs wss://
+  const wssUrl = cdpUrl.replace(/^https:\/\//, 'wss://').replace(/^http:\/\//, 'ws://')
+  const url = new URL('/live', baseUrl)
+  url.searchParams.set('wss', wssUrl)
+  return url.toString()
+}
+
+// ── Auth persistence ────────────────────────────────────────────────
+
+export interface CloudAuth {
+  token: string
+  baseUrl: string
+  /** When true, token is an API key sent via x-api-key header instead of Bearer */
+  isApiKey?: boolean
+}
+
+export function loadCloudAuth(): CloudAuth | null {
+  // API key takes highest priority (simplest for CI/VPS/headless)
+  const apiKey = process.env.TABWRIGHT_API_KEY || process.env.PLAYWRITER_API_KEY
+  if (apiKey) {
+    return {
+      token: apiKey,
+      baseUrl: process.env.TABWRIGHT_CLOUD_URL || process.env.PLAYWRITER_CLOUD_URL || DEFAULT_BASE_URL,
+      isApiKey: true,
+    }
+  }
+  // Session token env var (for CI with device flow tokens)
+  const envToken = process.env.TABWRIGHT_CLOUD_TOKEN || process.env.PLAYWRITER_CLOUD_TOKEN
+  if (envToken) {
+    return {
+      token: envToken,
+      baseUrl: process.env.TABWRIGHT_CLOUD_URL || process.env.PLAYWRITER_CLOUD_URL || DEFAULT_BASE_URL,
+    }
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(AUTH_FILE, 'utf-8'))
+    if (data.token) {
+      return { token: data.token, baseUrl: data.baseUrl || DEFAULT_BASE_URL }
+    }
+  } catch {
+    // No auth file
+  }
+  return null
+}
+
+export function saveCloudAuth(auth: CloudAuth): void {
+  const dir = path.dirname(AUTH_FILE)
+  fs.mkdirSync(dir, { recursive: true })
+  fs.writeFileSync(AUTH_FILE, JSON.stringify(auth, null, 2), { encoding: 'utf-8', mode: 0o600 })
+}
+
+// ── Cloud session status types ───────────────────────────────────────
+
+export interface CloudSessionStatus {
+  cloudSessionId: string
+  browserUseSessionId: string
+  index: number
+  createdAt: number
+  status: 'active' | 'stopped'
+  cdpUrl: string | null
+  liveUrl: string | null
+  timeoutAt: string
+}
+
+export interface ConnectResult {
+  cloudSessionId: string
+  cdpUrl: string | null
+  liveUrl: string | null
+  /** BU VM hard timeout (ISO string from server) */
+  timeoutAt?: string
+}
+
+// ── Client ──────────────────────────────────────────────────────────
+
+export class CloudClient {
+  private baseUrl: string
+  private token: string
+  private isApiKey: boolean
+
+  constructor(auth: CloudAuth) {
+    this.baseUrl = auth.baseUrl
+    this.token = auth.token
+    this.isApiKey = auth.isApiKey ?? false
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: Record<string, unknown>,
+  ): Promise<T> {
+    const url = new URL(path, this.baseUrl).toString()
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    }
+    // API keys use x-api-key header; session tokens use Authorization: Bearer
+    if (this.isApiKey) {
+      headers['x-api-key'] = this.token
+    } else {
+      headers['Authorization'] = `Bearer ${this.token}`
+    }
+
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    })
+
+    if (response.status === 401) {
+      throw new Error('Cloud auth expired or invalid. Run `tabwright cloud login` or set TABWRIGHT_API_KEY.')
+    }
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => '')
+      let detail = text
+      try {
+        const json = JSON.parse(text)
+        detail = json.error || json.message || text
+      } catch {
+        // use raw text
+      }
+      throw new Error(`Cloud API error: ${response.status} — ${detail}`)
+    }
+
+    return response.json() as Promise<T>
+  }
+
+  async getStatus(): Promise<{ sessions: CloudSessionStatus[] }> {
+    return this.request('GET', '/api/cloud/status')
+  }
+
+  async connect(options: {
+    proxyRegion?: string
+    customProxy?: { host: string; port: number; username?: string; password?: string }
+    /** Cloud browser timeout in minutes (1-240, default 60) */
+    timeout?: number
+  }): Promise<ConnectResult> {
+    return this.request('POST', '/api/cloud/connect', {
+      proxyRegion: options.proxyRegion,
+      customProxy: options.customProxy,
+      ...(options.timeout ? { timeout: options.timeout } : {}),
+    })
+  }
+
+  async disconnect(cloudSessionId: string): Promise<void> {
+    await this.request('POST', '/api/cloud/disconnect', { cloudSessionId })
+  }
+
+  /** Get a single session's status by cloudSessionId (from the status list). */
+  async getSessionStatus(cloudSessionId: string): Promise<CloudSessionStatus | null> {
+    const { sessions } = await this.getStatus()
+    return sessions.find((s) => {
+      return s.cloudSessionId === cloudSessionId
+    }) ?? null
+  }
+}
+
+/** Create a CloudClient from saved auth, or null if not logged in. */
+export function getCloudClient(): CloudClient | null {
+  const auth = loadCloudAuth()
+  if (!auth) return null
+  return new CloudClient(auth)
+}

package/src/create-logger.ts

@@ -0,0 +1,38 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import util from 'node:util'
+import stripAnsi from 'strip-ansi'
+import { LOG_FILE_PATH } from './utils.js'
+
+export type Logger = {
+  log(...args: unknown[]): Promise<void>
+  error(...args: unknown[]): Promise<void>
+  logFilePath: string
+}
+
+export function createFileLogger({ logFilePath }: { logFilePath?: string } = {}): Logger {
+  const resolvedLogFilePath = logFilePath || LOG_FILE_PATH
+  const logDir = path.dirname(resolvedLogFilePath)
+  if (!fs.existsSync(logDir)) {
+    fs.mkdirSync(logDir, { recursive: true })
+  }
+  fs.writeFileSync(resolvedLogFilePath, '')
+
+  let queue: Promise<void> = Promise.resolve()
+
+  const log = (...args: unknown[]): Promise<void> => {
+    const message = args
+      .map((arg) =>
+        typeof arg === 'string' ? arg : util.inspect(arg, { depth: null, colors: false, maxStringLength: 1000 }),
+      )
+      .join(' ')
+    queue = queue.then(() => fs.promises.appendFile(resolvedLogFilePath, stripAnsi(message) + '\n'))
+    return queue
+  }
+
+  return {
+    log,
+    error: log,
+    logFilePath: resolvedLogFilePath,
+  }
+}

package/src/debugger-examples-types.ts

@@ -0,0 +1,16 @@
+import type { Page, Locator } from '@xmorse/playwright-core'
+import type { ICDPSession } from './cdp-session.js'
+import type { Debugger } from './debugger.js'
+import type { Editor } from './editor.js'
+import type { StylesResult } from './styles.js'
+
+export declare const page: Page
+export declare const getCDPSession: (options: { page: Page }) => Promise<ICDPSession>
+export declare const createDebugger: (options: { cdp: ICDPSession }) => Debugger
+export declare const createEditor: (options: { cdp: ICDPSession }) => Editor
+export declare const getStylesForLocator: (options: {
+  locator: Locator
+  includeUserAgentStyles?: boolean
+}) => Promise<StylesResult>
+export declare const formatStylesAsText: (styles: StylesResult) => string
+export declare const console: { log: (...args: unknown[]) => void }

package/src/debugger-examples.ts

@@ -0,0 +1,66 @@
+import { page, getCDPSession, createDebugger, console } from './debugger-examples-types.js'
+
+// Example: List available scripts and set a breakpoint
+async function listScriptsAndSetBreakpoint() {
+  const cdp = await getCDPSession({ page })
+  const dbg = createDebugger({ cdp })
+  await dbg.enable()
+
+  const scripts = await dbg.listScripts({ search: 'app' })
+  console.log(scripts)
+
+  if (scripts.length > 0) {
+    const bpId = await dbg.setBreakpoint({ file: scripts[0].url, line: 100 })
+    console.log('Breakpoint set:', bpId)
+  }
+}
+
+// Example: Inspect state when paused at a breakpoint
+async function inspectWhenPaused() {
+  const cdp = await getCDPSession({ page })
+  const dbg = createDebugger({ cdp })
+  await dbg.enable()
+
+  if (dbg.isPaused()) {
+    const loc = await dbg.getLocation()
+    console.log('Paused at:', loc.url, 'line', loc.lineNumber)
+    console.log('Source:', loc.sourceContext)
+
+    const vars = await dbg.inspectLocalVariables()
+    console.log('Variables:', vars)
+
+    const result = await dbg.evaluate({ expression: 'myVar.length' })
+    console.log('myVar.length =', result.value)
+
+    await dbg.stepOver()
+  }
+}
+
+// Example: Step through code
+async function stepThroughCode() {
+  const cdp = await getCDPSession({ page })
+  const dbg = createDebugger({ cdp })
+  await dbg.enable()
+
+  await dbg.setBreakpoint({ file: 'https://example.com/app.js', line: 42 })
+
+  if (dbg.isPaused()) {
+    await dbg.stepOver()
+    await dbg.stepInto()
+    await dbg.stepOut()
+    await dbg.resume()
+  }
+}
+
+// Example: Cleanup all breakpoints
+async function cleanupBreakpoints() {
+  const cdp = await getCDPSession({ page })
+  const dbg = createDebugger({ cdp })
+
+  const breakpoints = dbg.listBreakpoints()
+  for (const bp of breakpoints) {
+    await dbg.deleteBreakpoint({ breakpointId: bp.id })
+  }
+}
+
+export { listScriptsAndSetBreakpoint, inspectWhenPaused, stepThroughCode, cleanupBreakpoints }