opendevbrowser 0.0.10 → 0.0.11

package/README.md

@@ -4,7 +4,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
 [![OpenCode Plugin](https://img.shields.io/badge/OpenCode-Plugin-green.svg?style=flat-square)](https://opencode.ai)
-[![Test Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg?style=flat-square)](https://github.com/freshtechbro/opendevbrowser)
+[![Test Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg?style=flat-square)](https://registry.npmjs.org/opendevbrowser)
 
 > **Script-first browser automation for AI agents.** Snapshot → Refs → Actions.
 
@@ -40,6 +40,12 @@ Recommended (CLI, installs plugin + config + bundled skills + extension assets):
 npx opendevbrowser --full --global --no-prompt
 ```
 
+Explicit flags (config + skills, no prompt):
+
+```bash
+npx opendevbrowser --global --with-config --skills-global --no-prompt
+```
+
 Manual fallback (edit OpenCode config):
 
 ```json
@@ -106,6 +112,107 @@ Restart OpenCode, then run `opendevbrowser_status` to verify the plugin is loade
 
 ---
 
+## Tool Reference
+
+OpenDevBrowser provides **30 tools** organized by category:
+
+### Session Management
+| Tool | Description |
+|------|-------------|
+| `opendevbrowser_launch` | Launch managed Chrome session with optional profile |
+| `opendevbrowser_connect` | Connect to existing Chrome CDP endpoint |
+| `opendevbrowser_disconnect` | Disconnect browser session |
+| `opendevbrowser_status` | Get session status and connection info |
+
+### Tab/Target Management
+| Tool | Description |
+|------|-------------|
+| `opendevbrowser_targets_list` | List all browser tabs/targets |
+| `opendevbrowser_target_use` | Switch to a specific tab by targetId |
+| `opendevbrowser_target_new` | Open new tab (optionally with URL) |
+| `opendevbrowser_target_close` | Close a tab by targetId |
+
+### Named Pages
+| Tool | Description |
+|------|-------------|
+| `opendevbrowser_page` | Open or focus a named page (logical tab alias) |
+| `opendevbrowser_list` | List all named pages in session |
+| `opendevbrowser_close` | Close a named page |
+
+### Navigation & Interaction
+| Tool | Description |
+|------|-------------|
+| `opendevbrowser_goto` | Navigate to URL |
+| `opendevbrowser_wait` | Wait for load state or element |
+| `opendevbrowser_snapshot` | Capture page accessibility tree with refs |
+| `opendevbrowser_click` | Click element by ref |
+| `opendevbrowser_type` | Type text into input by ref |
+| `opendevbrowser_select` | Select dropdown option by ref |
+| `opendevbrowser_scroll` | Scroll page or element |
+| `opendevbrowser_run` | Execute multiple actions in sequence |
+
+### DOM Inspection
+| Tool | Description |
+|------|-------------|
+| `opendevbrowser_dom_get_html` | Get outerHTML of element by ref |
+| `opendevbrowser_dom_get_text` | Get innerText of element by ref |
+
+### DevTools & Analysis
+| Tool | Description |
+|------|-------------|
+| `opendevbrowser_console_poll` | Poll console logs since sequence |
+| `opendevbrowser_network_poll` | Poll network requests since sequence |
+| `opendevbrowser_screenshot` | Capture page screenshot |
+| `opendevbrowser_perf` | Get page performance metrics |
+| `opendevbrowser_prompting_guide` | Get best-practice prompting guidance |
+
+### Export & Cloning
+| Tool | Description |
+|------|-------------|
+| `opendevbrowser_clone_page` | Export page as React component + CSS |
+| `opendevbrowser_clone_component` | Export element subtree as React component |
+
+### Skills
+| Tool | Description |
+|------|-------------|
+| `opendevbrowser_skill_list` | List available skills |
+| `opendevbrowser_skill_load` | Load a skill by name (with optional topic filter) |
+
+---
+
+## Bundled Skills
+
+OpenDevBrowser includes **5 task-specific skill packs**:
+
+| Skill | Purpose |
+|-------|---------|
+| `opendevbrowser-best-practices` | Core prompting patterns and workflow guidance |
+| `opendevbrowser-continuity-ledger` | Long-running task state management |
+| `login-automation` | Authentication flow patterns |
+| `form-testing` | Form validation and submission workflows |
+| `data-extraction` | Structured data scraping patterns |
+
+Skills are discovered from (priority order):
+1. `.opencode/skill/` (project)
+2. `~/.config/opencode/skill/` (global)
+3. `.claude/skills/` (compatibility)
+4. `~/.claude/skills/` (compatibility)
+5. Custom paths via `skillPaths` config
+
+Load a skill: `opendevbrowser_skill_load` with `name` and optional `topic` filter.
+
+---
+
+## Browser Modes
+
+| Mode | Tool | Use Case |
+|------|------|----------|
+| **Managed** | `opendevbrowser_launch` | Fresh browser, full control, automatic cleanup |
+| **CDP Connect** | `opendevbrowser_connect` | Attach to existing Chrome with `--remote-debugging-port` |
+| **Extension Relay** | Chrome Extension | Attach to logged-in tabs via relay server |
+
+---
+
 ## Chrome Extension (Optional)
 
 The extension enables **Mode C** - attach to existing logged-in browser tabs without launching a new browser.
@@ -114,17 +221,20 @@ The extension enables **Mode C** - attach to existing logged-in browser tabs wit
 
 The plugin and extension can automatically pair:
 
-1. **Plugin side**: Auto-generates secure token on first run (saved to config)
+1. **Plugin side**: Starts a local relay server and config discovery endpoint
 2. **Extension side**: Enable "Auto-Pair" toggle and click Connect
-3. Extension fetches token from plugin's relay server
+3. Extension fetches relay port from discovery, then fetches token from the relay server
 4. Connection established with color indicator (green = connected)
 
 ### Manual Setup
 
-1. Install extension from Chrome Web Store or load unpacked from `~/.cache/opencode/opendevbrowser-extension/`
-2. Open extension popup
-3. Enter same port/token as plugin config
-4. Click Connect
+1. Start OpenCode once so the plugin can extract the extension assets.
+2. Load unpacked from `~/.config/opencode/opendevbrowser/extension`
+   (fallback: `~/.cache/opencode/node_modules/opendevbrowser/extension`).
+3. Open extension popup
+4. Enter the same relay port and token as the plugin config
+   (if `relayToken` is missing, either add one to `opendevbrowser.jsonc` or use Auto-Pair).
+5. Click Connect
 
 ---
 
@@ -134,42 +244,56 @@ Optional config file: `~/.config/opencode/opendevbrowser.jsonc`
 
 ```jsonc
 {
+  // Browser settings
   "headless": false,
   "profile": "default",
   "persistProfile": true,
+  "chromePath": "/path/to/chrome",  // Custom Chrome executable
+  "flags": ["--disable-extensions"],  // Additional Chrome flags
+
+  // Snapshot limits
   "snapshot": { "maxChars": 16000, "maxNodes": 1000 },
+
+  // Export limits
   "export": { "maxNodes": 1000, "inlineStyles": true },
+
+  // DevTools output
   "devtools": { "showFullUrls": false, "showFullConsole": false },
+
+  // Security (all default false for safety)
   "security": {
     "allowRawCDP": false,
     "allowNonLocalCdp": false,
     "allowUnsafeExport": false
   },
+
+  // Skills configuration
+  "skills": {
+    "nudge": {
+      "enabled": true,
+      "keywords": ["form", "login", "extract", "scrape"],
+      "maxAgeMs": 60000
+    }
+  },
+  "skillPaths": ["./custom-skills"],  // Additional skill directories
+
+  // Continuity ledger
   "continuity": {
     "enabled": true,
     "filePath": "opendevbrowser_continuity.md",
     "nudge": {
       "enabled": true,
-      "keywords": [
-        "plan",
-        "multi-step",
-        "multi step",
-        "long-running",
-        "long running",
-        "refactor",
-        "migration",
-        "rollout",
-        "release",
-        "upgrade",
-        "investigate",
-        "follow-up",
-        "continue"
-      ],
+      "keywords": ["plan", "multi-step", "refactor", "migration"],
       "maxAgeMs": 60000
     }
   },
+
+  // Extension relay
   "relayPort": 8787,
-  "relayToken": "auto-generated-on-first-run"
+  "relayToken": "auto-generated-on-first-run",
+
+  // Updates
+  "checkForUpdates": false
 }
 ```
 
@@ -214,7 +338,7 @@ rm -rf ~/.cache/opencode/node_modules/opendevbrowser
 npx opendevbrowser --update
 ```
 
-Release checklist: `docs/DISTRIBUTION_PLAN.md`
+Release checklist: [docs/DISTRIBUTION_PLAN.md](docs/DISTRIBUTION_PLAN.md)
 
 ---
 
@@ -226,6 +350,8 @@ npm run build      # Compile to dist/
 npm run test       # Run tests with coverage
 npm run lint       # ESLint checks
 npm run extension:build  # Compile extension
+npm run version:check    # Verify package/extension version alignment
+npm run extension:pack   # Build extension zip for releases
 ```
 
 ---

package/dist/index.js

@@ -2276,21 +2276,30 @@ function buildContinuityNudgeMessage(filePath) {
 import { createServer } from "http";
 import { timingSafeEqual } from "crypto";
 import { WebSocket, WebSocketServer } from "ws";
+var DEFAULT_DISCOVERY_PORT = 8787;
+var CONFIG_PATH = "/config";
+var PAIR_PATH = "/pair";
 var RelayServer = class _RelayServer {
   running = false;
   baseUrl = null;
   port = null;
   server = null;
+  discoveryServer = null;
   extensionWss = null;
   cdpWss = null;
   extensionSocket = null;
   cdpSocket = null;
   extensionInfo = null;
   pairingToken = null;
+  configuredDiscoveryPort;
+  discoveryPort = null;
   handshakeAttempts = /* @__PURE__ */ new Map();
   cdpAllowlist = null;
   static MAX_HANDSHAKE_ATTEMPTS = 5;
   static RATE_LIMIT_WINDOW_MS = 6e4;
+  constructor(options = {}) {
+    this.configuredDiscoveryPort = options.discoveryPort ?? DEFAULT_DISCOVERY_PORT;
+  }
   async start(port = 8787) {
     if (this.running && this.baseUrl && this.port !== null) {
       return { url: this.baseUrl, port: this.port };
@@ -2335,7 +2344,15 @@ var RelayServer = class _RelayServer {
     this.server.on("request", (request, response) => {
       const pathname = new URL(request.url ?? "", "http://127.0.0.1").pathname;
       const origin = request.headers.origin;
-      if (pathname === "/pair" && request.method === "OPTIONS") {
+      if (pathname === CONFIG_PATH && request.method === "OPTIONS") {
+        this.handleConfigPreflight(origin, response);
+        return;
+      }
+      if (pathname === CONFIG_PATH && request.method === "GET") {
+        this.handleConfigRequest(origin, response);
+        return;
+      }
+      if (pathname === PAIR_PATH && request.method === "OPTIONS") {
         if (origin && origin.startsWith("chrome-extension://")) {
           response.setHeader("Access-Control-Allow-Origin", origin);
           response.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
@@ -2345,7 +2362,7 @@ var RelayServer = class _RelayServer {
         response.end();
         return;
       }
-      if (pathname === "/pair" && request.method === "GET") {
+      if (pathname === PAIR_PATH && request.method === "GET") {
         const isLocalhost = !origin || origin.startsWith("chrome-extension://");
         if (!isLocalhost) {
           response.writeHead(403, { "Content-Type": "application/json" });
@@ -2405,6 +2422,13 @@ var RelayServer = class _RelayServer {
     this.port = address.port;
     this.baseUrl = `ws://127.0.0.1:${address.port}`;
     this.running = true;
+    try {
+      await this.startDiscoveryServer();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`[opendevbrowser] Discovery server failed to start: ${message}`);
+      this.stopDiscoveryServer();
+    }
     return { url: this.baseUrl, port: address.port };
   }
   stop() {
@@ -2412,6 +2436,7 @@ var RelayServer = class _RelayServer {
     this.baseUrl = null;
     this.port = null;
     this.extensionInfo = null;
+    this.stopDiscoveryServer();
     if (this.extensionSocket) {
       this.extensionSocket.close(1e3, "Relay stopped");
       this.extensionSocket = null;
@@ -2440,6 +2465,12 @@ var RelayServer = class _RelayServer {
   getCdpUrl() {
     return this.baseUrl ? `${this.baseUrl}/cdp` : null;
   }
+  getDiscoveryPort() {
+    if (this.port !== null && this.port === this.configuredDiscoveryPort) {
+      return this.port;
+    }
+    return this.discoveryPort;
+  }
   setToken(token) {
     const trimmed = typeof token === "string" ? token.trim() : "";
     this.pairingToken = trimmed.length ? trimmed : null;
@@ -2460,6 +2491,81 @@ var RelayServer = class _RelayServer {
     }
     return false;
   }
+  isExtensionOrigin(origin) {
+    return Boolean(origin && origin.startsWith("chrome-extension://"));
+  }
+  handleConfigPreflight(origin, response) {
+    if (this.isExtensionOrigin(origin)) {
+      response.setHeader("Access-Control-Allow-Origin", origin);
+      response.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+      response.setHeader("Access-Control-Allow-Headers", "Content-Type");
+    }
+    response.writeHead(204);
+    response.end();
+  }
+  handleConfigRequest(origin, response) {
+    if (!this.isExtensionOrigin(origin)) {
+      response.writeHead(403, { "Content-Type": "application/json" });
+      response.end(JSON.stringify({ error: "Forbidden: extension origin required" }));
+      return;
+    }
+    if (origin) {
+      response.setHeader("Access-Control-Allow-Origin", origin);
+    }
+    if (this.port === null) {
+      response.writeHead(503, { "Content-Type": "application/json" });
+      response.end(JSON.stringify({ error: "Relay not running" }));
+      return;
+    }
+    response.writeHead(200, {
+      "Content-Type": "application/json",
+      "Cache-Control": "no-store"
+    });
+    response.end(JSON.stringify({
+      relayPort: this.port,
+      pairingRequired: Boolean(this.pairingToken)
+    }));
+  }
+  async startDiscoveryServer() {
+    if (this.port === null || this.discoveryServer) {
+      return;
+    }
+    if (this.configuredDiscoveryPort > 0 && this.configuredDiscoveryPort === this.port) {
+      return;
+    }
+    this.discoveryServer = createServer((request, response) => {
+      const pathname = new URL(request.url ?? "", "http://127.0.0.1").pathname;
+      const origin = request.headers.origin;
+      if (pathname === CONFIG_PATH && request.method === "OPTIONS") {
+        this.handleConfigPreflight(origin, response);
+        return;
+      }
+      if (pathname === CONFIG_PATH && request.method === "GET") {
+        this.handleConfigRequest(origin, response);
+        return;
+      }
+      response.writeHead(404);
+      response.end();
+    });
+    await new Promise((resolve, reject) => {
+      this.discoveryServer?.once("error", reject);
+      this.discoveryServer?.listen(this.configuredDiscoveryPort, "127.0.0.1", () => {
+        resolve();
+      });
+    });
+    const address = this.discoveryServer.address();
+    if (!address) {
+      throw new Error("Discovery server did not expose a port");
+    }
+    this.discoveryPort = address.port;
+  }
+  stopDiscoveryServer() {
+    if (this.discoveryServer) {
+      this.discoveryServer.close();
+      this.discoveryServer = null;
+    }
+    this.discoveryPort = null;
+  }
   isRateLimited(ip) {
     const now = Date.now();
     const record = this.handshakeAttempts.get(ip);