tabwright 1.0.0 → 1.0.1

package/src/cdp-session.ts

@@ -1,77 +0,0 @@
-import type { Page, CDPSession as PlaywrightCDPSession } from '@xmorse/playwright-core'
-import type { ProtocolMapping } from 'devtools-protocol/types/protocol-mapping.js'
-
-/**
- * Type-safe CDP session interface using devtools-protocol ProtocolMapping.
- * Provides autocomplete and type checking for CDP commands and events.
- * Return types are inferred from the command string (e.g. 'Page.getLayoutMetrics'
- * returns Protocol.Page.GetLayoutMetricsResponse).
- */
-export interface ICDPSession {
-  send<K extends keyof ProtocolMapping.Commands>(
-    method: K,
-    params?: ProtocolMapping.Commands[K]['paramsType'][0],
-    sessionId?: string | null,
-  ): Promise<ProtocolMapping.Commands[K]['returnType']>
-
-  on<K extends keyof ProtocolMapping.Events>(
-    event: K,
-    callback: (params: ProtocolMapping.Events[K][0]) => void,
-  ): unknown
-
-  off<K extends keyof ProtocolMapping.Events>(
-    event: K,
-    callback: (params: ProtocolMapping.Events[K][0]) => void,
-  ): unknown
-
-  detach(): Promise<void>
-  getSessionId?(): string | null
-}
-
-/**
- * Wraps Playwright's CDPSession (from context.getExistingCDPSession) into an ICDPSession.
- * This reuses Playwright's internal CDP WebSocket instead of creating a new one,
- * which is important for the relay server where Target.attachToTarget is intercepted.
- */
-export class PlaywrightCDPSessionAdapter implements ICDPSession {
-  private _playwrightSession: PlaywrightCDPSession
-
-  constructor(playwrightSession: PlaywrightCDPSession) {
-    this._playwrightSession = playwrightSession
-  }
-
-  async send<K extends keyof ProtocolMapping.Commands>(
-    method: K,
-    params?: ProtocolMapping.Commands[K]['paramsType'][0],
-  ): Promise<ProtocolMapping.Commands[K]['returnType']> {
-    return await this._playwrightSession.send(method as never, params as never)
-  }
-
-  on<K extends keyof ProtocolMapping.Events>(event: K, callback: (params: ProtocolMapping.Events[K][0]) => void): this {
-    this._playwrightSession.on(event as never, callback as never)
-    return this
-  }
-
-  off<K extends keyof ProtocolMapping.Events>(
-    event: K,
-    callback: (params: ProtocolMapping.Events[K][0]) => void,
-  ): this {
-    this._playwrightSession.off(event as never, callback as never)
-    return this
-  }
-
-  async detach(): Promise<void> {
-    await this._playwrightSession.detach()
-  }
-}
-
-/**
- * Gets a CDP session for a page by reusing Playwright's internal existing CDP session.
- * This uses the same WebSocket Playwright already has, avoiding new connections.
- * Works through the relay because it doesn't call Target.attachToTarget.
- */
-export async function getCDPSessionForPage({ page }: { page: Page }): Promise<PlaywrightCDPSessionAdapter> {
-  const context = page.context()
-  const playwrightSession = await context.getExistingCDPSession(page)
-  return new PlaywrightCDPSessionAdapter(playwrightSession)
-}

package/src/cdp-types.ts

@@ -1,158 +0,0 @@
-import type { Protocol } from 'devtools-protocol'
-import type { ProtocolMapping } from 'devtools-protocol/types/protocol-mapping.js'
-
-export type CDPCommandSource = 'playwriter'
-
-export type CDPCommandFor<T extends keyof ProtocolMapping.Commands> = {
-  id: number
-  sessionId?: string
-  method: T
-  params?: ProtocolMapping.Commands[T]['paramsType'][0]
-  source?: CDPCommandSource
-}
-
-export type CDPCommand = {
-  [K in keyof ProtocolMapping.Commands]: CDPCommandFor<K>
-}[keyof ProtocolMapping.Commands]
-
-export type CDPResponseFor<T extends keyof ProtocolMapping.Commands> = {
-  id: number
-  sessionId?: string
-  result?: ProtocolMapping.Commands[T]['returnType']
-  error?: { code?: number; message: string }
-}
-
-export type CDPResponse = {
-  [K in keyof ProtocolMapping.Commands]: CDPResponseFor<K>
-}[keyof ProtocolMapping.Commands]
-
-export type CDPEventFor<T extends keyof ProtocolMapping.Events> = {
-  method: T
-  sessionId?: string
-  params?: ProtocolMapping.Events[T][0]
-}
-
-export type CDPEvent = {
-  [K in keyof ProtocolMapping.Events]: CDPEventFor<K>
-}[keyof ProtocolMapping.Events]
-
-export type CDPResponseBase = {
-  id: number
-  sessionId?: string
-  result?: unknown
-  error?: { code?: number; message: string }
-}
-
-export type CDPEventBase = {
-  method: string
-  sessionId?: string
-  params?: unknown
-}
-
-export type CDPMessage = CDPCommand | CDPResponse | CDPEvent
-
-export type RelayServerEvents = {
-  'cdp:command': (data: { clientId: string; command: CDPCommand }) => void
-  'cdp:event': (data: { event: CDPEventBase; sessionId?: string }) => void
-  'cdp:response': (data: { clientId: string; response: CDPResponseBase; command: CDPCommand }) => void
-}
-
-export { Protocol, ProtocolMapping }
-
-// types tests. to see if types are right with some simple examples
-if (false as any) {
-  const browserVersionCommand = {
-    id: 1,
-    method: 'Browser.getVersion',
-  } satisfies CDPCommand
-
-  const browserVersionResponse = {
-    id: 1,
-    result: {
-      protocolVersion: '1.3',
-      product: 'Chrome',
-      revision: '123',
-      userAgent: 'Mozilla/5.0',
-      jsVersion: 'V8',
-    },
-  } satisfies CDPResponse
-
-  const targetAttachCommand = {
-    id: 2,
-    method: 'Target.setAutoAttach',
-    params: {
-      autoAttach: true,
-      waitForDebuggerOnStart: false,
-    },
-  } satisfies CDPCommand
-
-  const targetAttachResponse = {
-    id: 2,
-    result: undefined,
-  } satisfies CDPResponse
-
-  const attachedToTargetEvent = {
-    method: 'Target.attachedToTarget',
-    params: {
-      sessionId: 'session-1',
-      targetInfo: {
-        targetId: 'target-1',
-        type: 'page',
-        title: 'Example',
-        url: 'https://example.com',
-        attached: true,
-        canAccessOpener: false,
-      },
-      waitingForDebugger: false,
-    },
-  } satisfies CDPEvent
-
-  const consoleMessageEvent = {
-    method: 'Runtime.consoleAPICalled',
-    params: {
-      type: 'log',
-      args: [],
-      executionContextId: 1,
-      timestamp: 123456789,
-    },
-  } satisfies CDPEvent
-
-  const pageNavigateCommand = {
-    id: 3,
-    method: 'Page.navigate',
-    params: {
-      url: 'https://example.com',
-    },
-  } satisfies CDPCommand
-
-  const pageNavigateResponse = {
-    id: 3,
-    result: {
-      frameId: 'frame-1',
-    },
-  } satisfies CDPResponse
-
-  const networkRequestEvent = {
-    method: 'Network.requestWillBeSent',
-    sessionId: 'session-1',
-    params: {
-      requestId: 'req-1',
-      loaderId: 'loader-1',
-      documentURL: 'https://example.com',
-      request: {
-        url: 'https://example.com/api',
-        method: 'GET',
-        headers: {},
-        initialPriority: 'High',
-        referrerPolicy: 'no-referrer',
-      },
-      timestamp: 123456789,
-      wallTime: 123456789,
-      initiator: {
-        type: 'other',
-      },
-      redirectHasExtraInfo: false,
-      type: 'XHR',
-    },
-  } satisfies CDPEvent
-}

package/src/channel-owner-inspect.test.ts

@@ -1,94 +0,0 @@
-/**
- * Regression test for https://github.com/remorses/playwriter/issues/82
- *
- * User reported that running:
- *   tabwright -s 1 -e 'await page.goto("https://example.com")'
- * printed "all env vars" to the terminal.
- *
- * Root cause: `await page.goto(...)` auto-returns the Playwright Response.
- * util.inspect with depth:4 traversed Response → _connection → _platform →
- * env = process.env and dumped every environment variable.
- *
- * Fix: custom util.inspect handler on ChannelOwner and on the channel proxy
- * target. See playwright/packages/playwright-core/src/client/channelOwner.ts
- */
-import { describe, it, expect } from 'vitest'
-import util from 'node:util'
-
-describe('issue #82 - env var leak via util.inspect on Playwright objects', () => {
-  it('channel proxy target must NOT leak _platform.env via util.inspect', () => {
-    // Simulate the channel proxy structure from ChannelOwner._createChannel:
-    // a bare EventEmitter target wrapped in a Proxy, with _platform.env set
-    // to process.env. Before the fix, util.inspect traversed this.
-    const SECRET_KEY = 'ISSUE_82_TEST_SECRET_KEY'
-    const SECRET_VALUE = 'this-should-never-appear-in-inspect-output'
-
-    const base: any = {
-      _events: {},
-      _eventsCount: 0,
-      _maxListeners: undefined,
-      _platform: {
-        env: { [SECRET_KEY]: SECRET_VALUE, HOME: '/home/user' },
-        colors: {},
-      },
-    }
-
-    // Simulate the fix: custom inspect set directly on the base target.
-    base[Symbol.for('nodejs.util.inspect.custom')] = function () {
-      return 'Channel<Response@test-guid>'
-    }
-
-    const proxy = new Proxy(base, { get: (obj, prop) => obj[prop] })
-
-    // Inspect both directly and nested inside another object (as happens
-    // when auto-returning a Response whose _initializer.request is a channel)
-    const directInspect = util.inspect(proxy, { depth: 4 })
-    const nestedInspect = util.inspect(
-      { request: proxy, url: 'https://example.com' },
-      { depth: 4 },
-    )
-
-    expect(directInspect).not.toContain(SECRET_VALUE)
-    expect(directInspect).not.toContain(SECRET_KEY)
-    expect(nestedInspect).not.toContain(SECRET_VALUE)
-    expect(nestedInspect).not.toContain(SECRET_KEY)
-
-    expect(directInspect).toMatchInlineSnapshot(`"Channel<Response@test-guid>"`)
-    expect(nestedInspect).toMatchInlineSnapshot(`"{ request: Channel<Response@test-guid>, url: 'https://example.com' }"`)
-  })
-
-  it('ChannelOwner instance must NOT leak _platform.env via util.inspect', () => {
-    // Simulate a ChannelOwner instance — this is what the user actually
-    // auto-returns from `await page.goto(url)`.
-    const SECRET_VALUE = 'issue-82-channelowner-secret'
-
-    // Simulate a ChannelOwner instance via a plain object. The real fix in
-    // playwright-core adds a computed Symbol method to the ChannelOwner class.
-    const instance: any = {
-      _type: 'Response',
-      _guid: 'response@abc123',
-      _connection: { _platform: { env: { LEAKED: SECRET_VALUE } } },
-      _initializer: {
-        url: 'https://example.com/',
-        status: 200,
-        statusText: 'OK',
-      },
-    }
-    instance[Symbol.for('nodejs.util.inspect.custom')] = function (
-      _depth: number,
-      options: any,
-      inspect: (value: any, opts: any) => string,
-    ) {
-      const header = `${this._type}@${this._guid}`
-      const initializerDepth =
-        typeof options?.depth === 'number' ? Math.max(options.depth - 1, 0) : 2
-      return `${header} ${inspect(this._initializer, { ...options, depth: initializerDepth })}`
-    }
-    const output = util.inspect(instance, { depth: 4 })
-
-    expect(output).not.toContain(SECRET_VALUE)
-    expect(output).toMatchInlineSnapshot(
-      `"Response@response@abc123 { url: 'https://example.com/', status: 200, statusText: 'OK' }"`,
-    )
-  })
-})

package/src/chrome-discovery.test.ts

@@ -1,50 +0,0 @@
-import { describe, test, expect } from 'vitest'
-import { parseDevToolsActivePort } from './chrome-discovery.js'
-
-describe('parseDevToolsActivePort', () => {
-  test('parses valid contents', () => {
-    const result = parseDevToolsActivePort('9222\n/devtools/browser/abc-123-def\n')
-    expect(result).toMatchInlineSnapshot(`
-      {
-        "port": 9222,
-        "wsPath": "/devtools/browser/abc-123-def",
-      }
-    `)
-  })
-
-  test('parses with extra whitespace', () => {
-    const result = parseDevToolsActivePort('  9222  \n  /devtools/browser/abc  \n')
-    expect(result).toMatchInlineSnapshot(`
-      {
-        "port": 9222,
-        "wsPath": "/devtools/browser/abc",
-      }
-    `)
-  })
-
-  test('returns null for single line', () => {
-    expect(parseDevToolsActivePort('9222')).toBeNull()
-  })
-
-  test('returns null for empty string', () => {
-    expect(parseDevToolsActivePort('')).toBeNull()
-  })
-
-  test('returns null for invalid port', () => {
-    expect(parseDevToolsActivePort('abc\n/devtools/browser/123')).toBeNull()
-  })
-
-  test('returns null for port 0', () => {
-    expect(parseDevToolsActivePort('0\n/devtools/browser/123')).toBeNull()
-  })
-
-  test('returns null for port > 65535', () => {
-    expect(parseDevToolsActivePort('99999\n/devtools/browser/123')).toBeNull()
-  })
-
-  test('returns null for invalid ws path', () => {
-    expect(parseDevToolsActivePort('9222\n/some/other/path')).toBeNull()
-  })
-})
-
-

package/src/chrome-discovery.ts

@@ -1,220 +0,0 @@
-/**
- * Chrome instance discovery for direct CDP connections.
- *
- * Probes the default CDP port (9222) via GET /json/version.
- * If Chrome responds with a valid webSocketDebuggerUrl, the instance is usable.
- *
- * Chrome 136+ with chrome://inspect debugging returns 404 on all HTTP endpoints
- * but still accepts WebSocket connections on /devtools/browser/*. In that case
- * (status 'blocked'), we return a synthetic wsUrl — the actual WS connection
- * (which may trigger Chrome's approval dialog) only happens when the user
- * explicitly runs a command, not during discovery.
- *
- * For non-default ports or remote hosts, pass an explicit endpoint with
- * --direct host:port or --direct ws://....
- */
-
-export interface DiscoveredInstance {
-  browser: string
-  port: number
-  wsUrl: string
-  profiles: Array<{ name: string; email: string }>
-  dataDir: string | null
-}
-
-export interface ParsedActivePort {
-  port: number
-  wsPath: string
-}
-
-/**
- * Parse the contents of a DevToolsActivePort file.
- * Format: line 1 = port number, line 2 = /devtools/browser/{guid}
- */
-export function parseDevToolsActivePort(contents: string): ParsedActivePort | null {
-  const lines = contents.trim().split('\n')
-  if (lines.length < 2) {
-    return null
-  }
-  const port = parseInt(lines[0].trim(), 10)
-  if (isNaN(port) || port <= 0 || port > 65535) {
-    return null
-  }
-  const wsPath = lines[1].trim()
-  if (!wsPath.startsWith('/devtools/browser/')) {
-    return null
-  }
-  return { port, wsPath }
-}
-
-interface JsonVersionResponse {
-  Browser?: string
-  webSocketDebuggerUrl?: string
-  'Protocol-Version'?: string
-}
-
-type PortProbeStatus =
-  | { type: 'live'; wsUrl: string; browser: string }
-  /** HTTP response received but no CDP data (Chrome 136+ returns 404 on all HTTP
-   *  endpoints but still accepts WS on /devtools/browser/*). We can't get browser
-   *  info without a WS connection which would trigger Chrome's approval dialog. */
-  | { type: 'blocked'; port: number; hostname: string }
-  /** ECONNREFUSED or timeout — nothing is listening */
-  | { type: 'dead' }
-
-/**
- * Probe a port via GET /json/version.
- *
- * Returns:
- * - 'live'    — Chrome responded with valid CDP JSON containing webSocketDebuggerUrl
- * - 'blocked' — HTTP response received but no CDP info (Chrome 136+ default profile)
- * - 'dead'    — connection refused or timeout (nothing listening)
- */
-async function probePortStatus(port: number, hostname = '127.0.0.1'): Promise<PortProbeStatus> {
-  try {
-    const response = await fetch(`http://${hostname}:${port}/json/version`, {
-      signal: AbortSignal.timeout(1000),
-    })
-    if (!response.ok) {
-      await response.text() // consume body
-      return { type: 'blocked', port, hostname }
-    }
-    const data = (await response.json()) as JsonVersionResponse
-    if (data.webSocketDebuggerUrl) {
-      return { type: 'live', wsUrl: data.webSocketDebuggerUrl, browser: data.Browser || 'Unknown' }
-    }
-    return { type: 'blocked', port, hostname }
-  } catch {
-    return { type: 'dead' }
-  }
-}
-
-/**
- * Probe a port via GET /json/version.
- * Returns the webSocketDebuggerUrl and browser name, or null.
- */
-export async function probePort(port: number, hostname = '127.0.0.1'): Promise<{ wsUrl: string; browser: string } | null> {
-  const status = await probePortStatus(port, hostname)
-  if (status.type === 'live') {
-    return { wsUrl: status.wsUrl, browser: status.browser }
-  }
-  return null
-}
-
-/**
- * Discover Chrome on the default CDP port (9222).
- *
- * Probes /json/version. If Chrome responds with valid CDP JSON, returns the
- * instance with full browser info. If Chrome returns 404 (Chrome 136+ with
- * chrome://inspect debugging), returns a synthetic instance — the browser
- * version is unknown until an actual WS connection is made.
- */
-export async function discoverChromeInstances(): Promise<DiscoveredInstance[]> {
-  const status = await probePortStatus(9222)
-
-  if (status.type === 'live') {
-    return [
-      {
-        browser: parseBrowserVersion(status.browser),
-        port: 9222,
-        wsUrl: status.wsUrl,
-        profiles: [],
-        dataDir: null,
-      },
-    ]
-  }
-
-  if (status.type === 'blocked') {
-    return [
-      {
-        browser: 'Chrome',
-        port: status.port,
-        wsUrl: makeDirectWsUrl(status.hostname, status.port),
-        profiles: [],
-        dataDir: null,
-      },
-    ]
-  }
-
-  return []
-}
-
-/** Build a ws:// URL for direct CDP. The path is left bare — Chrome 136+
- *  accepts any value under /devtools/browser/. Call appendSessionToWsUrl()
- *  before connecting to make the path unique per session. */
-function makeDirectWsUrl(hostname: string, port: number): string {
-  return `ws://${hostname}:${port}/devtools/browser/`
-}
-
-/** Append a session ID to a /devtools/browser/ ws URL to make it unique.
- *  If the URL already has a full GUID path (e.g. from /json/version), return as-is. */
-export function appendSessionToWsUrl(wsUrl: string, sessionId: string): string {
-  // Only append if the path ends with / (our synthetic URLs from blocked probes)
-  if (wsUrl.endsWith('/')) {
-    return `${wsUrl}${sessionId}`
-  }
-  return wsUrl
-}
-
-/**
- * Resolve a --direct input value to a WebSocket URL.
- *
- * Accepts:
- * - ws:// or wss:// URL — returned as-is
- * - host:port — probes /json/version to get the webSocketDebuggerUrl
- *
- * Throws with a clear message if the endpoint can't be resolved.
- */
-export async function resolveDirectInput(input: string): Promise<string> {
-  if (input.startsWith('ws://') || input.startsWith('wss://')) {
-    return input
-  }
-
-  // Cloud browser providers (Browser Use, Browserbase) return https:// CDP URLs.
-  // Convert to wss:// since the WebSocket connection uses the same hostname.
-  if (input.startsWith('https://')) {
-    return 'wss://' + input.slice('https://'.length)
-  }
-  if (input.startsWith('http://')) {
-    return 'ws://' + input.slice('http://'.length)
-  }
-
-  const match = input.match(/^([^:]+):(\d+)$/)
-  if (!match) {
-    throw new Error(
-      `Invalid --direct value: expected a ws:// URL or host:port (e.g. localhost:9222), got: ${input}`,
-    )
-  }
-
-  const [, hostname, portStr] = match
-  const port = parseInt(portStr, 10)
-  const status = await probePortStatus(port, hostname)
-
-  if (status.type === 'live') {
-    return status.wsUrl
-  }
-
-  if (status.type === 'blocked') {
-    // Chrome 136+ returns 404 on HTTP but accepts WS on /devtools/browser/*
-    return makeDirectWsUrl(hostname, port)
-  }
-
-  throw new Error(
-    `Nothing found on ${hostname}:${port}. Is Chrome running with remote debugging enabled? ` +
-      `Try: chrome://inspect/#remote-debugging`,
-  )
-}
-
-function parseBrowserVersion(browserString: string): string {
-  if (browserString.startsWith('HeadlessChrome/')) {
-    return 'Chrome (Headless)'
-  }
-  if (browserString.startsWith('Chrome/')) {
-    return 'Chrome'
-  }
-  const slashIndex = browserString.indexOf('/')
-  if (slashIndex > 0) {
-    return browserString.slice(0, slashIndex)
-  }
-  return browserString
-}