playwriter 0.0.25 → 0.0.29

package/src/editor-examples.ts

@@ -0,0 +1,148 @@
+import { page, getCDPSession, createEditor, console } from './debugger-examples-types.js'
+
+// Example: List available scripts
+async function listScripts() {
+  const cdp = await getCDPSession({ page })
+  const editor = createEditor({ cdp })
+  await editor.enable()
+
+  const scripts = editor.list({ pattern: /app/ })
+  console.log(scripts)
+}
+
+// Example: Read a script with line numbers
+async function readScript() {
+  const cdp = await getCDPSession({ page })
+  const editor = createEditor({ cdp })
+  await editor.enable()
+
+  const { content, totalLines } = await editor.read({
+    url: 'https://example.com/app.js',
+  })
+  console.log('Total lines:', totalLines)
+  console.log(content)
+
+  const { content: partial } = await editor.read({
+    url: 'https://example.com/app.js',
+    offset: 100,
+    limit: 50,
+  })
+  console.log(partial)
+}
+
+// Example: Edit a script (exact string replacement)
+async function editScript() {
+  const cdp = await getCDPSession({ page })
+  const editor = createEditor({ cdp })
+  await editor.enable()
+
+  await editor.edit({
+    url: 'https://example.com/app.js',
+    oldString: 'const DEBUG = false',
+    newString: 'const DEBUG = true',
+  })
+
+  const dryRunResult = await editor.edit({
+    url: 'https://example.com/app.js',
+    oldString: 'old code',
+    newString: 'new code',
+    dryRun: true,
+  })
+  console.log('Dry run result:', dryRunResult)
+}
+
+// Example: Search across all scripts
+async function searchScripts() {
+  const cdp = await getCDPSession({ page })
+  const editor = createEditor({ cdp })
+  await editor.enable()
+
+  const matches = await editor.grep({ regex: /console\.log/ })
+  console.log(matches)
+
+  const todoMatches = await editor.grep({
+    regex: /TODO|FIXME/i,
+    pattern: /app/,
+  })
+  console.log(todoMatches)
+}
+
+// Example: Write entire script content
+async function writeScript() {
+  const cdp = await getCDPSession({ page })
+  const editor = createEditor({ cdp })
+  await editor.enable()
+
+  const { content } = await editor.read({ url: 'https://example.com/app.js' })
+  const newContent = content.replace(/console\.log/g, 'console.debug')
+
+  await editor.write({
+    url: 'https://example.com/app.js',
+    content: newContent,
+  })
+}
+
+// Example: Edit an inline script (scripts without URL get inline://{id} URLs)
+async function editInlineScript() {
+  const cdp = await getCDPSession({ page })
+  const editor = createEditor({ cdp })
+  await editor.enable()
+
+  const matches = await editor.grep({ regex: /myFunction/ })
+  if (matches.length > 0) {
+    const { url } = matches[0]
+    console.log('Found in:', url)
+
+    await editor.edit({
+      url,
+      oldString: 'return false',
+      newString: 'return true',
+    })
+  }
+}
+
+// Example: List and read CSS stylesheets
+async function readStylesheet() {
+  const cdp = await getCDPSession({ page })
+  const editor = createEditor({ cdp })
+  await editor.enable()
+
+  const stylesheets = await editor.list({ pattern: /\.css/ })
+  console.log('Stylesheets:', stylesheets)
+
+  if (stylesheets.length > 0) {
+    const { content, totalLines } = await editor.read({
+      url: stylesheets[0],
+    })
+    console.log('Total lines:', totalLines)
+    console.log(content)
+  }
+}
+
+// Example: Edit a CSS stylesheet
+async function editStylesheet() {
+  const cdp = await getCDPSession({ page })
+  const editor = createEditor({ cdp })
+  await editor.enable()
+
+  await editor.edit({
+    url: 'https://example.com/styles.css',
+    oldString: 'color: red',
+    newString: 'color: blue',
+  })
+}
+
+// Example: Search CSS for specific properties
+async function searchStyles() {
+  const cdp = await getCDPSession({ page })
+  const editor = createEditor({ cdp })
+  await editor.enable()
+
+  const matches = await editor.grep({
+    regex: /background-color/,
+    pattern: /\.css/,
+  })
+  console.log(matches)
+}
+
+export { listScripts, readScript, editScript, searchScripts, writeScript, editInlineScript, readStylesheet, editStylesheet, searchStyles }

package/src/editor.ts

@@ -0,0 +1,389 @@
+import type { CDPSession } from './cdp-session.js'
+
+export interface ReadResult {
+  content: string
+  totalLines: number
+  startLine: number
+  endLine: number
+}
+
+export interface SearchMatch {
+  url: string
+  lineNumber: number
+  lineContent: string
+}
+
+export interface EditResult {
+  success: boolean
+  stackChanged?: boolean
+}
+
+/**
+ * A class for viewing and editing web page scripts via Chrome DevTools Protocol.
+ * Provides a Claude Code-like interface: list, read, edit, grep.
+ *
+ * Edits are in-memory only and persist until page reload. They modify the running
+ * V8 instance but are not saved to disk or server.
+ *
+ * @example
+ * ```ts
+ * const cdp = await getCDPSession({ page })
+ * const editor = new Editor({ cdp })
+ * await editor.enable()
+ *
+ * // List available scripts
+ * const scripts = editor.list({ search: 'app' })
+ *
+ * // Read a script
+ * const { content } = await editor.read({ url: 'https://example.com/app.js' })
+ *
+ * // Edit a script
+ * await editor.edit({
+ *   url: 'https://example.com/app.js',
+ *   oldString: 'console.log("old")',
+ *   newString: 'console.log("new")'
+ * })
+ * ```
+ */
+export class Editor {
+  private cdp: CDPSession
+  private enabled = false
+  private scripts = new Map<string, string>()
+  private stylesheets = new Map<string, string>()
+  private sourceCache = new Map<string, string>()
+
+  constructor({ cdp }: { cdp: CDPSession }) {
+    this.cdp = cdp
+    this.setupEventListeners()
+  }
+
+  private setupEventListeners() {
+    this.cdp.on('Debugger.scriptParsed', (params) => {
+      if (!params.url.startsWith('chrome') && !params.url.startsWith('devtools')) {
+        const url = params.url || `inline://${params.scriptId}`
+        this.scripts.set(url, params.scriptId)
+        this.sourceCache.delete(params.scriptId)
+      }
+    })
+
+    this.cdp.on('CSS.styleSheetAdded', (params) => {
+      const header = params.header
+      if (header.sourceURL?.startsWith('chrome') || header.sourceURL?.startsWith('devtools')) {
+        return
+      }
+      const url = header.sourceURL || `inline-css://${header.styleSheetId}`
+      this.stylesheets.set(url, header.styleSheetId)
+      this.sourceCache.delete(header.styleSheetId)
+    })
+  }
+
+  /**
+   * Enables the editor. Must be called before other methods.
+   * Scripts are collected from Debugger.scriptParsed events.
+   * Reload the page after enabling to capture all scripts.
+   */
+  async enable(): Promise<void> {
+    if (this.enabled) {
+      return
+    }
+    await this.cdp.send('Debugger.disable')
+    await this.cdp.send('CSS.disable')
+    this.scripts.clear()
+    this.stylesheets.clear()
+    this.sourceCache.clear()
+    const resourcesReady = new Promise<void>((resolve) => {
+      let timeout: ReturnType<typeof setTimeout>
+      const listener = () => {
+        clearTimeout(timeout)
+        timeout = setTimeout(() => {
+          this.cdp.off('Debugger.scriptParsed', listener)
+          this.cdp.off('CSS.styleSheetAdded', listener)
+          resolve()
+        }, 100)
+      }
+      this.cdp.on('Debugger.scriptParsed', listener)
+      this.cdp.on('CSS.styleSheetAdded', listener)
+      timeout = setTimeout(() => {
+        this.cdp.off('Debugger.scriptParsed', listener)
+        this.cdp.off('CSS.styleSheetAdded', listener)
+        resolve()
+      }, 100)
+    })
+    await this.cdp.send('Debugger.enable')
+    await this.cdp.send('DOM.enable')
+    await this.cdp.send('CSS.enable')
+    await resourcesReady
+    this.enabled = true
+  }
+
+  private getIdByUrl(url: string): { scriptId: string } | { styleSheetId: string } {
+    const scriptId = this.scripts.get(url)
+    if (scriptId) {
+      return { scriptId }
+    }
+    const styleSheetId = this.stylesheets.get(url)
+    if (styleSheetId) {
+      return { styleSheetId }
+    }
+    const allUrls = [...Array.from(this.scripts.keys()), ...Array.from(this.stylesheets.keys())]
+    const available = allUrls.slice(0, 5)
+    throw new Error(`Resource not found: ${url}\nAvailable: ${available.join(', ')}${allUrls.length > 5 ? '...' : ''}`)
+  }
+
+  /**
+   * Lists available script and stylesheet URLs. Use pattern to filter by regex.
+   * Automatically enables the editor if not already enabled.
+   *
+   * @param options - Options
+   * @param options.pattern - Optional regex to filter URLs
+   * @returns Array of URLs
+   *
+   * @example
+   * ```ts
+   * // List all scripts and stylesheets
+   * const urls = await editor.list()
+   *
+   * // List only JS files
+   * const jsFiles = await editor.list({ pattern: /\.js/ })
+   *
+   * // List only CSS files
+   * const cssFiles = await editor.list({ pattern: /\.css/ })
+   *
+   * // Search for specific scripts
+   * const appScripts = await editor.list({ pattern: /app/ })
+   * ```
+   */
+  async list({ pattern }: { pattern?: RegExp } = {}): Promise<string[]> {
+    await this.enable()
+    const urls = [...Array.from(this.scripts.keys()), ...Array.from(this.stylesheets.keys())]
+
+    if (!pattern) {
+      return urls
+    }
+    return urls.filter((url) => {
+      const matches = pattern.test(url)
+      pattern.lastIndex = 0
+      return matches
+    })
+  }
+
+  /**
+   * Reads a script or stylesheet's source code by URL.
+   * Returns line-numbered content like Claude Code's Read tool.
+   * For inline scripts, use the `inline://` URL from list() or grep().
+   *
+   * @param options - Options
+   * @param options.url - Script or stylesheet URL (inline scripts have `inline://{id}` URLs)
+   * @param options.offset - Line number to start from (0-based, default 0)
+   * @param options.limit - Number of lines to return (default 2000)
+   * @returns Content with line numbers, total lines, and range info
+   *
+   * @example
+   * ```ts
+   * // Read by URL
+   * const { content, totalLines } = await editor.read({
+   *   url: 'https://example.com/app.js'
+   * })
+   *
+   * // Read a CSS file
+   * const { content } = await editor.read({ url: 'https://example.com/styles.css' })
+   *
+   * // Read lines 100-200
+   * const { content } = await editor.read({
+   *   url: 'https://example.com/app.js',
+   *   offset: 100,
+   *   limit: 100
+   * })
+   * ```
+   */
+  async read({ url, offset = 0, limit = 2000 }: { url: string; offset?: number; limit?: number }): Promise<ReadResult> {
+    await this.enable()
+    const id = this.getIdByUrl(url)
+    const source = await this.getSource(id)
+
+    const lines = source.split('\n')
+    const totalLines = lines.length
+    const startLine = Math.min(offset, totalLines)
+    const endLine = Math.min(offset + limit, totalLines)
+    const selectedLines = lines.slice(startLine, endLine)
+
+    const content = selectedLines.map((line, i) => `${String(startLine + i + 1).padStart(5)}| ${line}`).join('\n')
+
+    return {
+      content,
+      totalLines,
+      startLine: startLine + 1,
+      endLine,
+    }
+  }
+
+  private async getSource(id: { scriptId: string } | { styleSheetId: string }): Promise<string> {
+    if ('styleSheetId' in id) {
+      const cached = this.sourceCache.get(id.styleSheetId)
+      if (cached) {
+        return cached
+      }
+      const response = await this.cdp.send('CSS.getStyleSheetText', { styleSheetId: id.styleSheetId })
+      this.sourceCache.set(id.styleSheetId, response.text)
+      return response.text
+    }
+    const cached = this.sourceCache.get(id.scriptId)
+    if (cached) {
+      return cached
+    }
+    const response = await this.cdp.send('Debugger.getScriptSource', { scriptId: id.scriptId })
+    this.sourceCache.set(id.scriptId, response.scriptSource)
+    return response.scriptSource
+  }
+
+  /**
+   * Edits a script or stylesheet by replacing oldString with newString.
+   * Like Claude Code's Edit tool - performs exact string replacement.
+   *
+   * @param options - Options
+   * @param options.url - Script or stylesheet URL (inline scripts have `inline://{id}` URLs)
+   * @param options.oldString - Exact string to find and replace
+   * @param options.newString - Replacement string
+   * @param options.dryRun - If true, validate without applying (default false)
+   * @returns Result with success status
+   *
+   * @example
+   * ```ts
+   * // Replace a string in JS
+   * await editor.edit({
+   *   url: 'https://example.com/app.js',
+   *   oldString: 'const DEBUG = false',
+   *   newString: 'const DEBUG = true'
+   * })
+   *
+   * // Edit CSS
+   * await editor.edit({
+   *   url: 'https://example.com/styles.css',
+   *   oldString: 'color: red',
+   *   newString: 'color: blue'
+   * })
+   * ```
+   */
+  async edit({
+    url,
+    oldString,
+    newString,
+    dryRun = false,
+  }: {
+    url: string
+    oldString: string
+    newString: string
+    dryRun?: boolean
+  }): Promise<EditResult> {
+    await this.enable()
+    const id = this.getIdByUrl(url)
+    const source = await this.getSource(id)
+
+    const matchCount = source.split(oldString).length - 1
+    if (matchCount === 0) {
+      throw new Error(`oldString not found in ${url}`)
+    }
+    if (matchCount > 1) {
+      throw new Error(`oldString found ${matchCount} times in ${url}. Provide more context to make it unique.`)
+    }
+
+    const newSource = source.replace(oldString, newString)
+    return this.setSource(id, newSource, dryRun)
+  }
+
+  private async setSource(
+    id: { scriptId: string } | { styleSheetId: string },
+    content: string,
+    dryRun = false
+  ): Promise<EditResult> {
+    if ('styleSheetId' in id) {
+      await this.cdp.send('CSS.setStyleSheetText', { styleSheetId: id.styleSheetId, text: content })
+      if (!dryRun) {
+        this.sourceCache.set(id.styleSheetId, content)
+      }
+      return { success: true }
+    }
+    const response = await this.cdp.send('Debugger.setScriptSource', {
+      scriptId: id.scriptId,
+      scriptSource: content,
+      dryRun,
+    })
+    if (!dryRun) {
+      this.sourceCache.set(id.scriptId, content)
+    }
+    return { success: true, stackChanged: response.stackChanged }
+  }
+
+  /**
+   * Searches for a regex across all scripts and stylesheets.
+   * Like Claude Code's Grep tool - returns matching lines with context.
+   *
+   * @param options - Options
+   * @param options.regex - Regular expression to search for in file contents
+   * @param options.pattern - Optional regex to filter which URLs to search
+   * @returns Array of matches with url, line number, and line content
+   *
+   * @example
+   * ```ts
+   * // Search all scripts and stylesheets for "color"
+   * const matches = await editor.grep({ regex: /color/ })
+   *
+   * // Search only CSS files
+   * const matches = await editor.grep({
+   *   regex: /background-color/,
+   *   pattern: /\.css/
+   * })
+   *
+   * // Regex search for console methods in JS
+   * const matches = await editor.grep({
+   *   regex: /console\.(log|error|warn)/,
+   *   pattern: /\.js/
+   * })
+   * ```
+   */
+  async grep({ regex, pattern }: { regex: RegExp; pattern?: RegExp }): Promise<SearchMatch[]> {
+    await this.enable()
+
+    const matches: SearchMatch[] = []
+    const urls = await this.list({ pattern })
+
+    for (const url of urls) {
+      let source: string
+      try {
+        const id = this.getIdByUrl(url)
+        source = await this.getSource(id)
+      } catch {
+        continue
+      }
+
+      const lines = source.split('\n')
+      for (let i = 0; i < lines.length; i++) {
+        if (regex.test(lines[i])) {
+          matches.push({
+            url,
+            lineNumber: i + 1,
+            lineContent: lines[i].trim().slice(0, 200),
+          })
+          regex.lastIndex = 0
+        }
+      }
+    }
+
+    return matches
+  }
+
+  /**
+   * Writes entire content to a script or stylesheet, replacing all existing code.
+   * Use with caution - prefer edit() for targeted changes.
+   *
+   * @param options - Options
+   * @param options.url - Script or stylesheet URL (inline scripts have `inline://{id}` URLs)
+   * @param options.content - New content
+   * @param options.dryRun - If true, validate without applying (default false, only works for JS)
+   */
+  async write({ url, content, dryRun = false }: { url: string; content: string; dryRun?: boolean }): Promise<EditResult> {
+    await this.enable()
+    const id = this.getIdByUrl(url)
+    return this.setSource(id, content, dryRun)
+  }
+}

package/src/index.ts

@@ -1,2 +1,2 @@
-export * from './extension/cdp-relay.js'
+export * from './cdp-relay.js'
 export * from './utils.js'

package/src/mcp-client.ts

@@ -9,23 +9,28 @@ const __filename = url.fileURLToPath(import.meta.url)
 
 export interface CreateTransportOptions {
   clientName?: string
+  port?: number
 }
 
-export async function createTransport(args: string[]): Promise<{
+export async function createTransport({ args = [], port }: { args?: string[]; port?: number } = {}): Promise<{
   transport: Transport
   stderr: Stream | null
 }> {
+  const env: Record<string, string> = {
+    ...process.env as Record<string, string>,
+    DEBUG: 'playwriter:mcp:test',
+    DEBUG_COLORS: '0',
+    DEBUG_HIDE_DATE: '1',
+  }
+  if (port) {
+    env.PLAYWRITER_PORT = String(port)
+  }
   const transport = new StdioClientTransport({
     command: 'pnpm',
-    args: ['vite-node', path.join(path.dirname(__filename), 'mcp.ts'), ...args],
+    args: ['vite-node', path.join(path.dirname(__filename), 'cli.ts'), ...args],
     cwd: path.join(path.dirname(__filename), '..'),
     stderr: 'pipe',
-    env: {
-      ...process.env,
-      DEBUG: 'playwriter:mcp:test',
-      DEBUG_COLORS: '0',
-      DEBUG_HIDE_DATE: '1',
-    },
+    env,
   })
 
   return {
@@ -44,7 +49,7 @@ export async function createMCPClient(options?: CreateTransportOptions): Promise
     version: '1.0.0',
   })
 
-  const { transport, stderr } = await createTransport([])
+  const { transport, stderr } = await createTransport({ port: options?.port })
 
   let stderrBuffer = ''
   stderr?.on('data', (data) => {