cdp-tunnel 1.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,92 @@
+name: Publish to npm
+
+on:
+  # 当发布 release 时触发
+  release:
+    types: [published]
+
+  # push 到 main 分支时自动更新 patch 版本
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - '**.md'
+      - '.github/**'
+
+  # 手动触发
+  workflow_dispatch:
+    inputs:
+      version_type:
+        description: '版本类型'
+        required: true
+        default: 'patch'
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      # 检出代码
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      # 设置 Node.js
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      # 配置 Git
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      # 从 Release 名称提取版本号，或使用手动输入
+      - name: Update version
+        run: |
+          if [ "${{ github.event_name }}" = "release" ]; then
+            # 从 release tag 提取版本号（去掉 v 前缀）
+            VERSION=${GITHUB_REF_NAME#v}
+            npm version $VERSION --no-git-tag-version
+          elif [ "${{ github.event_name }}" = "push" ]; then
+            # push 到 main，自动更新 patch 版本
+            npm version patch --no-git-tag-version
+          else
+            # 手动触发，使用选择的版本类型
+            npm version ${{ inputs.version_type }} --no-git-tag-version
+          fi
+          cat package.json | grep version
+
+      # 提交版本更新
+      - name: Commit version update
+        run: |
+          git add package.json package-lock.json
+          git commit -m "chore: bump version to $(cat package.json | grep '"version"' | head -1 | awk -F: '{ print $2 }' | sed 's/[",]//g' | tr -d ' ')"
+          git push
+
+      # 安装依赖
+      - name: Install dependencies
+        run: npm ci
+
+      # 运行测试（如果有）
+      - name: Run tests
+        run: npm test || echo "No tests found"
+        continue-on-error: true
+
+      # 发布到 npm
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/release-assets.yml

@@ -0,0 +1,50 @@
+name: Create Release Assets
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build-assets:
+    runs-on: ubuntu-latest
+    
+    steps:
+      # 检出代码
+      - name: Checkout code
+        uses: actions/checkout@v4
+      
+      # 打包扩展
+      - name: Pack extension
+        run: |
+          cd extension-new
+          zip -r ../cdp-tunnel-extension.zip .
+          cd ..
+          ls -lh cdp-tunnel-extension.zip
+      
+      # 上传扩展到 Release
+      - name: Upload extension to Release
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ github.event.release.upload_url }}
+          asset_path: ./cdp-tunnel-extension.zip
+          asset_name: cdp-tunnel-extension.zip
+          asset_content_type: application/zip
+      
+      # 打包完整项目
+      - name: Pack full project
+        run: |
+          zip -r cdp-tunnel-full.zip . -x "*.git*" -x "node_modules/*" -x "test/*"
+          ls -lh cdp-tunnel-full.zip
+      
+      # 上传完整项目到 Release
+      - name: Upload full project to Release
+        uses: actions/upload-release-asset@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ github.event.release.upload_url }}
+          asset_path: ./cdp-tunnel-full.zip
+          asset_name: cdp-tunnel-full.zip
+          asset_content_type: application/zip

package/LICENSE

@@ -0,0 +1,81 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+2. Grant of Copyright License.
+
+   Subject to the terms and conditions of this License, the Licensor
+   hereby grants to You a worldwide, royalty-free, non-exclusive,
+   perpetual, irrevocable copyright license to reproduce, prepare
+   derivative works of, publicly display, publicly perform, sublicense,
+   and distribute the Work and such derivative works in source and
+   object code form.
+
+3. Grant of Patent License.
+
+   Subject to the terms and conditions of this License, the Licensor
+   hereby grants to You a worldwide, royalty-free, non-exclusive,
+   perpetual, irrevocable patent license to make, have made, use,
+   offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by the Licensor that are necessarily infringed by their
+   contribution(s) alone or by combination of their contribution(s)
+   with the Work to which such contribution(s) was submitted.
+
+4. Attribution Requirement.
+
+   Any derivative works based on this Software must include clear
+   attribution to the original project:
+
+   - Project name: CDP Tunnel
+   - Author: dyyz1993
+   - Source: https://github.com/dyyz1993/cdp-tunnel
+
+   This attribution should appear in:
+   - Documentation or README files
+   - About/Info screens of the derivative software
+   - Source code comments (where practical)
+
+5. Disclaimer of Warranty.
+
+   Unless required by applicable law or agreed to in writing, Licensor
+   provides the Work (and each Contributor provides its Contributions)
+   on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+   either express or implied, including, without limitation, any
+   warranties or conditions of TITLE, NON-INFRINGEMENT,
+   MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+
+6. Limitation of Liability.
+
+   In no event and under no legal theory, whether in tort (including
+   negligence), contract, or otherwise, unless required by applicable
+   law (such as deliberate and grossly negligent acts) or agreed to in
+   writing, shall any Contributor be liable to You for damages, including any
+   direct, indirect, special, incidental, or consequential damages of
+   any character arising as a result of this License or out of the use
+   or inability to use the Work (including but not limited to damages
+   for loss of goodwill, work stoppage, computer failure or malfunction,
+   or any and all other commercial damages or losses), even if such
+   Contributor has been advised of the possibility of such damages.
+
+================================================================================
+
+Copyright (C) 2025 CDP Tunnel
+https://github.com/dyyz1993/cdp-tunnel

package/PUBLISH.md

@@ -0,0 +1,65 @@
+# 发布到 npm 指南
+
+## 自动发布（推荐）
+
+本项目已配置 GitHub Actions，支持自动发布到 npm。
+
+### 配置步骤
+
+1. **获取 npm Token**
+   - 登录 [npmjs.com](https://www.npmjs.com/)
+   - 进入 Account → Access Tokens
+   - 生成新的 **Automation** token
+   - 复制 token（以 `npm_` 开头）
+
+2. **添加到 GitHub Secrets**
+   - 打开 GitHub 仓库 → Settings → Secrets and variables → Actions
+   - 点击 "New repository secret"
+   - Name: `NPM_TOKEN`
+   - Value: 刚才复制的 npm token
+   - 点击 "Add secret"
+
+3. **发布新版本**
+   - 在 GitHub 上创建新的 Release
+   - 设置版本号（如 v1.0.1）
+   - 填写发布说明
+   - 点击 "Publish release"
+   - GitHub Actions 会自动发布到 npm
+
+### 手动触发
+
+也可以在 GitHub Actions 页面手动触发发布：
+- 进入 Actions → Publish to npm
+- 点击 "Run workflow"
+
+## 手动发布
+
+如果不想使用 GitHub Actions，也可以手动发布：
+
+```bash
+# 1. 登录 npm
+npm login
+
+# 2. 更新版本号
+npm version patch  # 或 minor / major
+
+# 3. 发布
+npm publish --access public
+```
+
+## 版本号规则
+
+- `patch`: 修复 bug（1.0.0 → 1.0.1）
+- `minor`: 新增功能（1.0.0 → 1.1.0）
+- `major`: 重大更新（1.0.0 → 2.0.0）
+
+## 验证发布
+
+发布后可以在 npm 上查看：
+https://www.npmjs.com/package/cdp-tunnel
+
+安装测试：
+```bash
+npm install -g cdp-tunnel
+cdp-tunnel --version
+```

package/README.md

@@ -0,0 +1,228 @@
+# CDP Tunnel
+
+<p align="center">
+  <img src="extension-new/icons/icon128.png" alt="CDP Tunnel Logo" width="128" height="128">
+</p>
+
+<p align="center">
+  <strong>Chrome DevTools Protocol Bridge</strong>
+</p>
+
+<p align="center">
+  A Chrome extension that exposes your browser as a CDP endpoint,<br>
+  supporting multiple Playwright/Puppeteer clients to connect simultaneously.
+</p>
+
+<p align="center">
+  <a href="docs/README_CN.md">中文文档</a> | 
+  <a href="https://github.com/dyyz1993/cdp-tunnel">GitHub</a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/github/stars/dyyz1993/cdp-tunnel?style=social" alt="GitHub stars">
+  <img src="https://img.shields.io/github/forks/dyyz1993/cdp-tunnel?style=social" alt="GitHub forks">
+  <img src="https://img.shields.io/github/watchers/dyyz1993/cdp-tunnel?style=social" alt="GitHub watchers">
+</p>
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Proxy Server                             │
+│                     (localhost:9221)                            │
+│                                                                 │
+│   /plugin  ←─── Chrome Extension (WebSocket)                    │
+│   HTTP     ←─── Playwright/Puppeteer Clients                    │
+└─────────────────────────────────────────────────────────────────┘
+         ↑              ↑              ↑
+         │              │              │
+    Client 1       Client 2       Client 3
+   (clientId_1)    (clientId_2)    (clientId_3)
+```
+
+## Features
+
+- **Multi-client Support** - Multiple Playwright/Puppeteer clients can connect simultaneously
+- **Message Isolation** - Pages created by each client are owned by that client
+- **Configuration Page** - Visualize connection status, client list, and controlled pages
+- **Auto Reconnect** - Extension automatically reconnects to the server
+
+## Screenshot
+
+![Config Page](docs/config-page-screenshot.png)
+
+## Quick Start
+
+### Option 1: Install via npm (Recommended)
+
+```bash
+# Install globally
+npm install -g cdp-tunnel
+
+# Start server
+cdp-tunnel start
+
+# Check status
+cdp-tunnel status
+
+# Install Chrome extension (opens interactive guide)
+cdp-tunnel extension
+```
+
+### Option 2: Download from GitHub Releases
+
+1. Go to [GitHub Releases](https://github.com/dyyz1993/cdp-tunnel/releases)
+2. Download `cdp-tunnel-extension.zip` from the latest release
+3. Unzip the file
+4. Open `chrome://extensions/` in Chrome
+5. Enable "Developer mode"
+6. Click "Load unpacked"
+7. Select the unzipped extension directory
+
+### Option 3: Manual Installation
+
+#### 1. Start the Proxy Server
+
+```bash
+cd server
+npm install
+node proxy-server.js
+```
+
+The server will start on `localhost:9221`.
+
+#### 2. Install Chrome Extension
+
+1. Open `chrome://extensions/`
+2. Enable "Developer mode"
+3. Click "Load unpacked"
+4. Select the `extension-new` directory
+
+#### 3. Connect the Extension
+
+Click the extension icon, enter the server address in the configuration page, and click "Save and Connect".
+
+### 3. Client Connection
+
+```javascript
+// Playwright
+const { chromium } = require('playwright');
+
+const browser = await chromium.connectOverCDP('http://localhost:9221');
+const context = browser.contexts()[0];
+const page = await context.newPage();
+await page.goto('https://example.com');
+
+// Puppeteer
+const puppeteer = require('puppeteer');
+
+const browser = await puppeteer.connect({
+  browserWSEndpoint: 'ws://localhost:9221'
+});
+const page = await browser.newPage();
+await page.goto('https://example.com');
+```
+
+### 4. Using with agent-browser
+
+[agent-browser](https://github.com/nick1udwig/agent-browser) is a browser automation CLI that can connect to CDP Tunnel:
+
+```bash
+# Install agent-browser
+npm install -g agent-browser
+
+# Connect to CDP Tunnel
+agent-browser --cdp http://localhost:9221 open https://example.com
+
+# Take a snapshot
+agent-browser --cdp http://localhost:9221 snapshot -i
+
+# Interact with elements
+agent-browser --cdp http://localhost:9221 click @e1
+agent-browser --cdp http://localhost:9221 fill @e2 "hello"
+
+# Take screenshot
+agent-browser --cdp http://localhost:9221 screenshot output.png
+```
+
+This allows you to control the browser through CDP Tunnel using simple CLI commands.
+
+## Multi-client Usage
+
+All clients connect to the same endpoint `http://localhost:9221`. The server automatically assigns a unique `clientId` to each connection.
+
+```javascript
+// Multiple clients can connect simultaneously
+const browser1 = await chromium.connectOverCDP('http://localhost:9221');
+const browser2 = await chromium.connectOverCDP('http://localhost:9221');
+const browser3 = await chromium.connectOverCDP('http://localhost:9221');
+
+// Pages created by each client are independent
+const page1 = await browser1.contexts()[0].newPage();
+const page2 = await browser2.contexts()[0].newPage();
+const page3 = await browser3.contexts()[0].newPage();
+```
+
+## Configuration Page
+
+Click the extension icon to open the configuration page, where you can view:
+
+- **CDP Client List** - Shows connected Playwright/Puppeteer clients
+- **Controlled Pages List** - Shows controlled pages with click-to-navigate support
+- **Activity Log** - Connection status change records
+
+## Project Structure
+
+```
+cdp-tunnel/
+├── server/
+│   └── proxy-server.js      # Proxy server
+├── extension-new/
+│   ├── background.js        # Extension Service Worker
+│   ├── config-page-preview.html  # Configuration page
+│   ├── config-page.js       # Configuration page script
+│   ├── core/
+│   │   ├── state.js         # State management
+│   │   └── websocket.js     # WebSocket connection management
+│   └── features/
+│       ├── cdp-router.js    # CDP message routing
+│       └── screencast.js    # Screenshot functionality
+└── tests/
+    ├── playwright-single.js      # Single client test
+    ├── playwright-multi.js       # Multi-client test
+    └── playwright-interactive.js # Interactive test
+```
+
+## Testing
+
+```bash
+# Single client test
+node tests/playwright-single.js
+
+# Multi-client test
+node tests/playwright-multi.js
+
+# Interactive test
+node tests/playwright-interactive.js
+```
+
+## Notes
+
+1. **Port Availability** - Ensure port 9221 is not in use
+2. **Extension Permissions** - The extension requires `debugger`, `tabs`, and other permissions
+3. **Browser Limitation** - Only one extension can control a browser via debugger at a time
+
+## License
+
+This project is licensed under the Apache License 2.0 with Attribution Requirement.
+
+See [LICENSE](LICENSE) for details.
+
+---
+
+If you use this project in your work, please include attribution:
+- Project: CDP Tunnel
+- Author: dyyz1993
+- Source: https://github.com/dyyz1993/cdp-tunnel