tabwright 1.0.0

package/src/styles.ts

@@ -0,0 +1,343 @@
+import type { ICDPSession } from './cdp-session.js'
+import type { Locator } from '@xmorse/playwright-core'
+
+export interface StyleSource {
+  url: string
+  line: number
+  column: number
+}
+
+export type StyleDeclarations = Record<string, string>
+
+export interface StyleRule {
+  selector: string
+  source: StyleSource | null
+  origin: 'regular' | 'user-agent' | 'injected' | 'inspector'
+  declarations: StyleDeclarations
+  inheritedFrom: string | null
+}
+
+export interface StylesResult {
+  element: string
+  inlineStyle: StyleDeclarations | null
+  rules: StyleRule[]
+}
+
+interface CSSProperty {
+  name: string
+  value: string
+  important?: boolean
+}
+
+interface CSSStyle {
+  cssProperties: CSSProperty[]
+  cssText?: string
+}
+
+interface CSSRule {
+  selectorList: { text: string }
+  style: CSSStyle
+  styleSheetId?: string
+  origin: string
+}
+
+interface RuleMatch {
+  rule: CSSRule
+  matchingSelectors: number[]
+}
+
+interface InheritedStyleEntry {
+  inlineStyle?: CSSStyle
+  matchedCSSRules: RuleMatch[]
+}
+
+interface SourceRange {
+  startLine: number
+  startColumn: number
+  endLine: number
+  endColumn: number
+}
+
+interface CSSStyleSheetHeader {
+  styleSheetId: string
+  sourceURL?: string
+  origin: string
+}
+
+export async function getStylesForLocator({
+  locator,
+  cdp: cdpSession,
+  includeUserAgentStyles = false,
+}: {
+  locator: Locator
+  cdp: ICDPSession
+  includeUserAgentStyles?: boolean
+}): Promise<StylesResult> {
+  const cdp = cdpSession
+  await cdp.send('DOM.enable')
+  await cdp.send('CSS.enable')
+
+  const elementHandle = await locator.elementHandle()
+  if (!elementHandle) {
+    throw new Error('Could not get element handle from locator')
+  }
+
+  const remoteObject = (elementHandle as any)._channel?.objectId
+    ? { objectId: (elementHandle as any)._channel.objectId }
+    : null
+
+  let backendNodeId: number
+  if (remoteObject?.objectId) {
+    const nodeInfo = await cdp.send('DOM.describeNode', {
+      objectId: remoteObject.objectId,
+    })
+    backendNodeId = nodeInfo.node.backendNodeId
+  } else {
+    const box = await elementHandle.boundingBox()
+    if (!box) {
+      throw new Error('Element has no bounding box')
+    }
+    const docResult = await cdp.send('DOM.getDocument', { depth: 0 })
+    const nodeAtPoint = await cdp.send('DOM.getNodeForLocation', {
+      x: Math.round(box.x + box.width / 2),
+      y: Math.round(box.y + box.height / 2),
+    })
+    backendNodeId = nodeAtPoint.backendNodeId
+  }
+
+  const pushResult = await cdp.send('DOM.pushNodesByBackendIdsToFrontend', {
+    backendNodeIds: [backendNodeId],
+  })
+  const nodeId = pushResult.nodeIds[0]
+
+  if (!nodeId) {
+    throw new Error('Could not get nodeId for element')
+  }
+
+  const nodeInfo = await cdp.send('DOM.describeNode', { nodeId })
+  const elementDescription = formatElementDescription(nodeInfo.node)
+
+  const matchedStyles = await cdp.send('CSS.getMatchedStylesForNode', { nodeId })
+
+  const stylesheetUrls = new Map<string, string>()
+
+  const processStyleSheetId = async (styleSheetId: string | undefined): Promise<StyleSource | null> => {
+    if (!styleSheetId) {
+      return null
+    }
+
+    if (!stylesheetUrls.has(styleSheetId)) {
+      try {
+        const header = await cdp.send('CSS.getStyleSheetText', { styleSheetId })
+        stylesheetUrls.set(styleSheetId, '')
+      } catch {
+        stylesheetUrls.set(styleSheetId, '')
+      }
+    }
+
+    return null
+  }
+
+  const rules: StyleRule[] = []
+
+  if (matchedStyles.matchedCSSRules) {
+    for (const ruleMatch of matchedStyles.matchedCSSRules) {
+      const rule = ruleMatch.rule
+      const sourceRange = (rule as any).selectorList?.range as SourceRange | undefined
+      const styleSheetId = rule.styleSheetId
+
+      let source: StyleSource | null = null
+      if (styleSheetId && sourceRange) {
+        const styleSheet = (matchedStyles as any).cssStyleSheetHeaders?.find(
+          (h: CSSStyleSheetHeader) => h.styleSheetId === styleSheetId,
+        )
+        const url =
+          styleSheet?.sourceURL || (rule as any).origin === 'user-agent' ? 'user-agent' : `stylesheet:${styleSheetId}`
+
+        source = {
+          url: (rule as any).styleSheetId ? await getStylesheetUrl(cdp, styleSheetId) : 'user-agent',
+          line: sourceRange.startLine + 1,
+          column: sourceRange.startColumn,
+        }
+      }
+
+      rules.push({
+        selector: rule.selectorList.text,
+        source,
+        origin: rule.origin as StyleRule['origin'],
+        declarations: extractDeclarations(rule.style),
+        inheritedFrom: null,
+      })
+    }
+  }
+
+  if (matchedStyles.inherited) {
+    for (let i = 0; i < matchedStyles.inherited.length; i++) {
+      const inheritedEntry = matchedStyles.inherited[i] as InheritedStyleEntry
+      const ancestorDesc = `ancestor[${i + 1}]`
+
+      if (inheritedEntry.inlineStyle) {
+        const declarations = extractDeclarations(inheritedEntry.inlineStyle)
+        if (Object.keys(declarations).length > 0) {
+          rules.push({
+            selector: 'element.style',
+            source: null,
+            origin: 'regular',
+            declarations,
+            inheritedFrom: ancestorDesc,
+          })
+        }
+      }
+
+      for (const ruleMatch of inheritedEntry.matchedCSSRules) {
+        const rule = ruleMatch.rule
+        const sourceRange = (rule as any).selectorList?.range as SourceRange | undefined
+        const styleSheetId = rule.styleSheetId
+
+        let source: StyleSource | null = null
+        if (styleSheetId && sourceRange) {
+          source = {
+            url: await getStylesheetUrl(cdp, styleSheetId),
+            line: sourceRange.startLine + 1,
+            column: sourceRange.startColumn,
+          }
+        }
+
+        const declarations = extractDeclarations(rule.style)
+        if (Object.keys(declarations).length > 0) {
+          rules.push({
+            selector: rule.selectorList.text,
+            source,
+            origin: rule.origin as StyleRule['origin'],
+            declarations,
+            inheritedFrom: ancestorDesc,
+          })
+        }
+      }
+    }
+  }
+
+  let inlineStyle: StyleDeclarations | null = null
+  if (matchedStyles.inlineStyle) {
+    const declarations = extractDeclarations(matchedStyles.inlineStyle as CSSStyle)
+    if (Object.keys(declarations).length > 0) {
+      inlineStyle = declarations
+    }
+  }
+
+  const filteredRules = includeUserAgentStyles ? rules : rules.filter((r) => r.origin !== 'user-agent')
+
+  return {
+    element: elementDescription,
+    inlineStyle,
+    rules: filteredRules,
+  }
+}
+
+function extractDeclarations(style: CSSStyle): StyleDeclarations {
+  if (!style?.cssProperties) {
+    return {}
+  }
+
+  const result: StyleDeclarations = {}
+  for (const prop of style.cssProperties) {
+    if (!prop.value || prop.value === 'initial' || prop.name.startsWith('-webkit-')) {
+      continue
+    }
+    const value = prop.important ? `${prop.value} !important` : prop.value
+    result[prop.name] = value
+  }
+  return result
+}
+
+function formatElementDescription(node: any): string {
+  let desc = node.localName || node.nodeName?.toLowerCase() || 'element'
+
+  if (node.attributes) {
+    const attrs: Record<string, string> = {}
+    for (let i = 0; i < node.attributes.length; i += 2) {
+      attrs[node.attributes[i]] = node.attributes[i + 1]
+    }
+
+    if (attrs.id) {
+      desc += `#${attrs.id}`
+    }
+    if (attrs.class) {
+      desc += `.${attrs.class.split(' ').join('.')}`
+    }
+  }
+
+  return desc
+}
+
+async function getStylesheetUrl(cdp: ICDPSession, styleSheetId: string): Promise<string> {
+  try {
+    await cdp.send('CSS.getStyleSheetText', { styleSheetId })
+    return `stylesheet:${styleSheetId}`
+  } catch {
+    return `stylesheet:${styleSheetId}`
+  }
+}
+
+export function formatStylesAsText(styles: StylesResult): string {
+  const lines: string[] = []
+
+  lines.push(`Element: ${styles.element}`)
+  lines.push('')
+
+  if (styles.inlineStyle) {
+    lines.push('Inline styles:')
+    for (const [prop, value] of Object.entries(styles.inlineStyle)) {
+      lines.push(`  ${prop}: ${value}`)
+    }
+    lines.push('')
+  }
+
+  const directRules = styles.rules.filter((r) => !r.inheritedFrom)
+  const inheritedRules = styles.rules.filter((r) => r.inheritedFrom)
+
+  if (directRules.length > 0) {
+    lines.push('Matched rules:')
+    for (const rule of directRules) {
+      lines.push(`  ${rule.selector} {`)
+      const sourceInfo = rule.source ? ` /* ${rule.source.url}:${rule.source.line}:${rule.source.column} */` : ''
+      if (sourceInfo) {
+        lines.push(`   ${sourceInfo}`)
+      }
+      for (const [prop, value] of Object.entries(rule.declarations)) {
+        lines.push(`    ${prop}: ${value};`)
+      }
+      lines.push('  }')
+    }
+    lines.push('')
+  }
+
+  if (inheritedRules.length > 0) {
+    const byAncestor = new Map<string, StyleRule[]>()
+    for (const rule of inheritedRules) {
+      const key = rule.inheritedFrom!
+      if (!byAncestor.has(key)) {
+        byAncestor.set(key, [])
+      }
+      byAncestor.get(key)!.push(rule)
+    }
+
+    for (const [ancestor, rules] of byAncestor) {
+      lines.push(`Inherited from ${ancestor}:`)
+      for (const rule of rules) {
+        lines.push(`  ${rule.selector} {`)
+        const sourceInfo = rule.source ? ` /* ${rule.source.url}:${rule.source.line}:${rule.source.column} */` : ''
+        if (sourceInfo) {
+          lines.push(`   ${sourceInfo}`)
+        }
+        for (const [prop, value] of Object.entries(rule.declarations)) {
+          lines.push(`    ${prop}: ${value};`)
+        }
+        lines.push('  }')
+      }
+      lines.push('')
+    }
+  }
+
+  return lines.join('\n')
+}

package/src/tabwright-agent-skill.test.ts

@@ -0,0 +1,61 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { afterEach, describe, expect, test } from 'vitest'
+import { getTabwrightAgentSkillStatus, installTabwrightAgentSkill } from './tabwright-agent-skill.js'
+
+const tempDirs: string[] = []
+
+afterEach(() => {
+  tempDirs.splice(0).map((dir) => {
+    fs.rmSync(dir, { recursive: true, force: true })
+    return dir
+  })
+})
+
+function createFixture(): { bundledSkillPath: string; codexHome: string } {
+  const tmpRoot = path.resolve(process.cwd(), '..', 'tmp')
+  fs.mkdirSync(tmpRoot, { recursive: true })
+  const dir = fs.mkdtempSync(path.join(tmpRoot, 'tabwright-agent-skill-test-'))
+  tempDirs.push(dir)
+  const bundledSkillPath = path.join(dir, 'bundled', 'SKILL.md')
+  fs.mkdirSync(path.dirname(bundledSkillPath), { recursive: true })
+  fs.writeFileSync(bundledSkillPath, '---\nname: tabwright\ndescription: Test skill\n---\n\nUse Tabwright.\n')
+  return { bundledSkillPath, codexHome: path.join(dir, 'codex-home') }
+}
+
+describe('Tabwright agent skill installation', () => {
+  test('installs the bundled skill and reports it current', () => {
+    const fixture = createFixture()
+    const missing = getTabwrightAgentSkillStatus(fixture)
+    expect(missing.state).toBe('missing')
+    expect(missing.installCommand).toBe('tabwright skill install --target codex')
+
+    const installed = installTabwrightAgentSkill(fixture)
+    expect(installed.fileStatus).toBe('created')
+    expect(installed.state).toBe('current')
+    expect(fs.readFileSync(installed.installedPath, 'utf-8')).toBe(
+      fs.readFileSync(fixture.bundledSkillPath, 'utf-8'),
+    )
+
+    const unchanged = installTabwrightAgentSkill(fixture)
+    expect(unchanged.fileStatus).toBe('unchanged')
+  })
+
+  test('requires force before replacing a different installed skill', () => {
+    const fixture = createFixture()
+    const installedPath = path.join(fixture.codexHome, 'skills', 'tabwright', 'SKILL.md')
+    fs.mkdirSync(path.dirname(installedPath), { recursive: true })
+    fs.writeFileSync(installedPath, 'locally edited skill\n')
+
+    const outdated = getTabwrightAgentSkillStatus(fixture)
+    expect(outdated.state).toBe('outdated')
+    expect(outdated.installCommand).toBe('tabwright skill install --target codex --force')
+    expect(() => {
+      installTabwrightAgentSkill(fixture)
+    }).toThrow(/Use --force to overwrite/)
+
+    const updated = installTabwrightAgentSkill({ ...fixture, overwrite: true })
+    expect(updated.fileStatus).toBe('updated')
+    expect(updated.state).toBe('current')
+  })
+})

package/src/tabwright-agent-skill.ts

@@ -0,0 +1,105 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { getInstalledTabwrightPackageDir } from './package-paths.js'
+
+export type TabwrightAgentSkillTarget = 'codex'
+export type TabwrightAgentSkillState = 'missing' | 'current' | 'outdated'
+
+export interface TabwrightAgentSkillStatus {
+  target: TabwrightAgentSkillTarget
+  state: TabwrightAgentSkillState
+  bundledPath: string
+  installedPath: string
+  bundledSha256: string
+  installedSha256?: string
+  installCommand: string
+}
+
+export interface TabwrightAgentSkillInstallResult extends TabwrightAgentSkillStatus {
+  fileStatus: 'created' | 'updated' | 'unchanged'
+  next: string[]
+}
+
+export function getBundledTabwrightAgentSkillPath(options: { bundledSkillPath?: string } = {}): string {
+  if (options.bundledSkillPath) {
+    return options.bundledSkillPath
+  }
+  const packageDir = getInstalledTabwrightPackageDir()
+  const repositoryRoot = path.join(packageDir, '..')
+  const packagedSkillPath = path.join(packageDir, 'dist', 'agent-skills', 'tabwright', 'SKILL.md')
+  const repositorySkillPath = path.join(repositoryRoot, 'skills', 'tabwright', 'SKILL.md')
+  const candidates = fs.existsSync(path.join(repositoryRoot, '.git'))
+    ? [repositorySkillPath, packagedSkillPath]
+    : [packagedSkillPath]
+  const bundledPath = candidates.find((candidate) => {
+    return fs.existsSync(candidate)
+  })
+  if (!bundledPath) {
+    throw new Error(`Bundled Tabwright skill not found under ${packageDir}. Rebuild or reinstall the CLI.`)
+  }
+  return bundledPath
+}
+
+export function getTabwrightAgentSkillStatus(options: {
+  target?: TabwrightAgentSkillTarget
+  codexHome?: string
+  bundledSkillPath?: string
+} = {}): TabwrightAgentSkillStatus {
+  const target = options.target || 'codex'
+  const bundledPath = getBundledTabwrightAgentSkillPath({ bundledSkillPath: options.bundledSkillPath })
+  const installedPath = path.join(getCodexHome(options.codexHome), 'skills', 'tabwright', 'SKILL.md')
+  const bundledContent = fs.readFileSync(bundledPath, 'utf-8')
+  const installedContent = fs.existsSync(installedPath) ? fs.readFileSync(installedPath, 'utf-8') : undefined
+  const state: TabwrightAgentSkillState = (() => {
+    if (installedContent === undefined) {
+      return 'missing'
+    }
+    return installedContent === bundledContent ? 'current' : 'outdated'
+  })()
+  return {
+    target,
+    state,
+    bundledPath,
+    installedPath,
+    bundledSha256: sha256(bundledContent),
+    ...(installedContent === undefined ? {} : { installedSha256: sha256(installedContent) }),
+    installCommand: `tabwright skill install --target ${target}${state === 'outdated' ? ' --force' : ''}`,
+  }
+}
+
+export function installTabwrightAgentSkill(options: {
+  target?: TabwrightAgentSkillTarget
+  codexHome?: string
+  bundledSkillPath?: string
+  overwrite?: boolean
+} = {}): TabwrightAgentSkillInstallResult {
+  const before = getTabwrightAgentSkillStatus(options)
+  if (before.state === 'current') {
+    return {
+      ...before,
+      fileStatus: 'unchanged',
+      next: ['Restart or open a new Codex thread so it can load the Tabwright skill.'],
+    }
+  }
+  if (before.state === 'outdated' && !options.overwrite) {
+    throw new Error(`Installed Tabwright skill differs from this CLI: ${before.installedPath}. Use --force to overwrite.`)
+  }
+  fs.mkdirSync(path.dirname(before.installedPath), { recursive: true })
+  fs.copyFileSync(before.bundledPath, before.installedPath)
+  const after = getTabwrightAgentSkillStatus(options)
+  return {
+    ...after,
+    fileStatus: before.state === 'missing' ? 'created' : 'updated',
+    next: ['Restart or open a new Codex thread so it can load the Tabwright skill.'],
+  }
+}
+
+function getCodexHome(codexHome?: string): string {
+  return path.resolve(codexHome || process.env.CODEX_HOME || path.join(os.homedir(), '.codex'))
+}
+
+function sha256(content: string): string {
+  return crypto.createHash('sha256').update(content).digest('hex')
+}

package/src/test-declarations.ts

@@ -0,0 +1,13 @@
+import type { ExtensionState } from 'mcp-extension/src/types.js'
+
+declare global {
+  var toggleExtensionForActiveTab: () => Promise<{ isConnected: boolean; state: ExtensionState }>
+  var getExtensionState: () => ExtensionState
+  var disconnectEverything: () => Promise<void>
+
+  // Browser globals used in evaluate() calls
+  var window: any
+  var document: any
+}
+
+export {}

package/src/test-utils.test.ts

@@ -0,0 +1,70 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { describe, expect, test } from 'vitest'
+import { startTabwrightCDPRelayServer } from './cdp-relay.js'
+import {
+  getExtensionServiceWorker,
+  getLegacyExtensionLaunchArgs,
+  isExtensionLoadUnavailableError,
+  launchPersistentContextWithExtensions,
+} from './test-utils.js'
+
+describe('extension test browser launch', () => {
+  test('builds the legacy extension launch fallback flags', () => {
+    const extensionPaths = ['./extension-one', './extension-two']
+    const args = getLegacyExtensionLaunchArgs({ extensionPaths })
+    const resolvedPaths = extensionPaths.map((extensionPath) => {
+      return path.resolve(extensionPath)
+    })
+
+    expect(args).toContain(`--disable-extensions-except=${resolvedPaths.join(',')}`)
+    expect(args).toContain(`--load-extension=${resolvedPaths.join(',')}`)
+  })
+
+  test('recognizes older browsers without Extensions.loadUnpacked', () => {
+    expect(
+      isExtensionLoadUnavailableError(
+        new Error("Protocol error (Extensions.loadUnpacked): 'Extensions.loadUnpacked' wasn't found"),
+      ),
+    ).toBe(true)
+    expect(isExtensionLoadUnavailableError(new Error('Method not found'))).toBe(true)
+    expect(isExtensionLoadUnavailableError(new Error('Manifest is invalid'))).toBe(false)
+  })
+
+  test.runIf(Boolean(process.env.PLAYWRITER_TEST_EXTENSION_PATH))(
+    'loads an unpacked extension in the installed Chrome build',
+    async () => {
+      const extensionPath = process.env.PLAYWRITER_TEST_EXTENSION_PATH
+      if (!extensionPath) {
+        throw new Error('PLAYWRITER_TEST_EXTENSION_PATH is required')
+      }
+
+      const tempRoot = path.join(process.cwd(), 'tmp')
+      fs.mkdirSync(tempRoot, { recursive: true })
+      const userDataDir = fs.mkdtempSync(path.join(tempRoot, 'pw-extension-load-test-'))
+      const relayServer = await startTabwrightCDPRelayServer({
+        port: Number(process.env.PLAYWRITER_TEST_RELAY_PORT) || 19_997,
+      })
+      try {
+        const browserContext = await launchPersistentContextWithExtensions({
+          userDataDir,
+          extensionPaths: [extensionPath],
+        })
+        try {
+          const serviceWorker = await getExtensionServiceWorker(browserContext).catch(async (error: unknown) => {
+            const session = await browserContext.browser()?.newBrowserCDPSession()
+            const targets = session ? await session.send('Target.getTargets') : null
+            throw new Error(`No extension service worker target was visible: ${JSON.stringify(targets)}`, { cause: error })
+          })
+          expect(serviceWorker.url()).toMatch(/^chrome-extension:\/\//)
+        } finally {
+          await browserContext.close()
+        }
+      } finally {
+        relayServer.close()
+        fs.rmSync(userDataDir, { recursive: true, force: true })
+      }
+    },
+    60_000,
+  )
+})