tabwright 1.0.0

package/src/clean-html.ts

@@ -0,0 +1,141 @@
+import { Page, Locator } from '@xmorse/playwright-core'
+import { formatHtmlForPrompt } from './htmlrewrite.js'
+import { createSmartDiff } from './diff-utils.js'
+
+export interface GetCleanHTMLOptions {
+  locator: Locator | Page
+  search?: string | RegExp
+  showDiffSinceLastCall?: boolean
+  includeStyles?: boolean
+  maxAttrLen?: number
+  maxContentLen?: number
+}
+
+// Store last HTML snapshots per locator/page for diffing
+const lastHtmlSnapshots: WeakMap<Page, Map<string, string>> = new WeakMap()
+
+function isPage(obj: any): obj is Page {
+  return obj && typeof obj.content === 'function' && typeof obj.goto === 'function'
+}
+
+function isRegExp(value: any): value is RegExp {
+  return (
+    typeof value === 'object' && value !== null && typeof value.test === 'function' && typeof value.exec === 'function'
+  )
+}
+
+function getSnapshotKey(locator: Locator | Page): string {
+  if (isPage(locator)) {
+    return 'page'
+  }
+  return `locator:${locator.selector()}`
+}
+
+export async function getCleanHTML(options: GetCleanHTMLOptions): Promise<string> {
+  const {
+    locator,
+    search,
+    showDiffSinceLastCall = !search,
+    includeStyles = false,
+    maxAttrLen = 200,
+    maxContentLen = 500,
+  } = options
+
+  // Get raw HTML
+  let rawHtml: string
+  let page: Page
+
+  if (isPage(locator)) {
+    page = locator
+    rawHtml = await locator.content()
+  } else {
+    page = locator.page()
+    rawHtml = await locator.innerHTML()
+  }
+
+  // Clean the HTML using formatHtmlForPrompt
+  const cleanedHtml = await formatHtmlForPrompt({
+    html: rawHtml,
+    keepStyles: includeStyles,
+    maxAttrLen,
+    maxContentLen,
+  })
+
+  // Sanitize to remove unpaired surrogates that break JSON encoding
+  let htmlStr = cleanedHtml.toWellFormed?.() ?? cleanedHtml
+
+  // Store snapshot and handle diffing
+  let pageSnapshots = lastHtmlSnapshots.get(page)
+  if (!pageSnapshots) {
+    pageSnapshots = new Map()
+    lastHtmlSnapshots.set(page, pageSnapshots)
+  }
+
+  const snapshotKey = getSnapshotKey(locator)
+  const previousSnapshot = pageSnapshots.get(snapshotKey)
+  pageSnapshots.set(snapshotKey, htmlStr)
+
+  // Diff defaults off when search is provided, but agent can explicitly enable both
+  if (showDiffSinceLastCall && previousSnapshot) {
+    const diffResult = createSmartDiff({
+      oldContent: previousSnapshot,
+      newContent: htmlStr,
+      label: 'html',
+    })
+    if (diffResult.type === 'no-change') {
+      return 'No changes since last call. Use showDiffSinceLastCall: false to see full content.'
+    }
+    return diffResult.content
+  }
+
+  // Handle search
+  if (search) {
+    const lines = htmlStr.split('\n')
+    const matchIndices: number[] = []
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      let isMatch = false
+      if (isRegExp(search)) {
+        isMatch = search.test(line)
+      } else {
+        isMatch = line.includes(search)
+      }
+
+      if (isMatch) {
+        matchIndices.push(i)
+        if (matchIndices.length >= 10) break
+      }
+    }
+
+    if (matchIndices.length === 0) {
+      return 'No matches found'
+    }
+
+    // Collect lines with 5 lines of context above and below each match
+    const CONTEXT_LINES = 5
+    const includedLines = new Set<number>()
+    for (const idx of matchIndices) {
+      const start = Math.max(0, idx - CONTEXT_LINES)
+      const end = Math.min(lines.length - 1, idx + CONTEXT_LINES)
+      for (let i = start; i <= end; i++) {
+        includedLines.add(i)
+      }
+    }
+
+    // Build result with separators between non-contiguous sections
+    const sortedIndices = [...includedLines].sort((a, b) => a - b)
+    const result: string[] = []
+    for (let i = 0; i < sortedIndices.length; i++) {
+      const lineIdx = sortedIndices[i]
+      if (i > 0 && sortedIndices[i - 1] !== lineIdx - 1) {
+        result.push('---')
+      }
+      result.push(lines[lineIdx])
+    }
+
+    return result.join('\n')
+  }
+
+  return htmlStr
+}

package/src/cli-help.test.ts

@@ -0,0 +1,123 @@
+// Verifies CLI help stays runnable without loading browser-start-only dependencies.
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { describe, expect, test } from 'vitest'
+
+const execFileAsync = promisify(execFile)
+const currentDir = path.dirname(fileURLToPath(import.meta.url))
+const tabwrightDir = path.resolve(currentDir, '..')
+const viteNodeBinary = path.join(
+  tabwrightDir,
+  'node_modules',
+  '.bin',
+  process.platform === 'win32' ? 'vite-node.cmd' : 'vite-node',
+)
+
+async function runCli(args: string[]): Promise<{ stdout: string; stderr: string }> {
+  return execFileAsync(viteNodeBinary, ['src/cli.ts', ...args], {
+    cwd: tabwrightDir,
+    env: process.env,
+  })
+}
+
+describe('tabwright cli help', () => {
+  test('renders root help without crashing', async () => {
+    const { stdout, stderr } = await runCli(['--help'])
+
+    expect(stdout).toContain('tabwright')
+    expect(stdout).toContain('doctor')
+    expect(stdout).toContain('serve')
+    expect(stderr).toBe('')
+  }, 30000)
+
+  test('renders doctor help without starting the relay', async () => {
+    const { stdout, stderr } = await runCli(['doctor', '--help'])
+
+    expect(stdout).toContain('single best next step')
+    expect(stdout).toContain('--json')
+    expect(stderr).toBe('')
+  }, 30000)
+
+  test('reports an unreachable remote relay without crashing', async () => {
+    const { stdout, stderr } = await runCli(['doctor', '--host', 'http://127.0.0.1:1', '--json'])
+    const report = JSON.parse(stdout) as {
+      ready: boolean
+      checks: Array<{ id: string; status: string }>
+    }
+
+    expect(report.ready).toBe(false)
+    expect(report.checks).toEqual(
+      expect.arrayContaining([expect.objectContaining({ id: 'relay', status: 'fail' })]),
+    )
+    expect(stderr).toBe('')
+  }, 30000)
+
+  test('renders serve help without crashing', async () => {
+    const { stdout, stderr } = await runCli(['serve', '--help'])
+
+    expect(stdout).toContain('Start the relay server on this machine')
+    expect(stdout).toContain('--replace')
+    expect(stderr).toBe('')
+  }, 30000)
+
+  test('renders replay discovery and compact evidence help', async () => {
+    const listHelp = await runCli(['replay', 'list', '--help'])
+    const indexHelp = await runCli(['replay', 'index', '--help'])
+
+    expect(listHelp.stdout).toContain('next commands')
+    expect(listHelp.stdout).toContain('--limit')
+    expect(indexHelp.stdout).toContain('--full')
+    expect(listHelp.stderr).toBe('')
+    expect(indexHelp.stderr).toBe('')
+  }, 30000)
+
+  test('teaches a fresh agent how to package and install capabilities', async () => {
+    const { stdout, stderr } = await runCli(['skill'])
+    const discoverySkill = fs.readFileSync(path.resolve(tabwrightDir, '..', 'skills', 'tabwright', 'SKILL.md'), 'utf-8')
+
+    expect(stdout).toContain('tabwright capability pack query-user')
+    expect(stdout).toContain('tabwright capability install ./query-user.tgz')
+    expect(stdout).toContain('A shared capability always installs as `draft`')
+    expect(discoverySkill).toContain('tabwright capability pack <capability-id>')
+    expect(discoverySkill).toContain('tabwright capability install ./<capability-id>.tgz')
+    expect(stderr).toBe('')
+  }, 30000)
+
+  test('exposes bundled Tabwright skill installation and status commands', async () => {
+    const installHelp = await runCli(['skill', 'install', '--help'])
+    const statusHelp = await runCli(['skill', 'status', '--help'])
+
+    expect(installHelp.stdout).toContain('bundled with this CLI')
+    expect(installHelp.stdout).toContain('--codex-home')
+    expect(installHelp.stdout).toContain('--force')
+    expect(statusHelp.stdout).toContain('matches this CLI')
+    expect(statusHelp.stdout).toContain('--json')
+    expect(installHelp.stderr).toBe('')
+    expect(statusHelp.stderr).toBe('')
+  }, 30000)
+
+  test('unknown command exits with code 1', async () => {
+    try {
+      await runCli(['run'])
+      expect.unreachable('should have thrown')
+    } catch (error: any) {
+      expect(error.code).toBe(1)
+      expect(error.stderr).toContain('Unknown command: run')
+      expect(error.stderr).toContain('tabwright --help')
+    }
+  }, 30000)
+
+  test('unknown subcommand exits with code 1', async () => {
+    try {
+      await runCli(['session', 'nonexistent'])
+      expect.unreachable('should have thrown')
+    } catch (error: any) {
+      expect(error.code).toBe(1)
+      expect(error.stdout).toContain('Unknown command: session nonexistent')
+      expect(error.stdout).toContain('session new')
+    }
+  }, 30000)
+})