opendevbrowser 0.0.10 → 0.0.12

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
@@ -77,6 +83,34 @@ Restart OpenCode, then run `opendevbrowser_status` to verify the plugin is loade
 
 ---
 
+### CLI Automation Quick Start
+
+Run a local daemon for persistent sessions, then drive automation via CLI commands:
+
+```bash
+# Start daemon
+npx opendevbrowser serve
+
+# Launch a session
+npx opendevbrowser launch --start-url https://example.com
+
+# Capture a snapshot
+npx opendevbrowser snapshot --session-id <session-id>
+
+# Interact by ref
+npx opendevbrowser click --session-id <session-id> --ref r12
+```
+
+For single-shot scripts:
+
+```bash
+npx opendevbrowser run --script ./script.json --output-format json
+```
+
+Use `--output-format json|stream-json` for automation-friendly output.
+
+---
+
 ## Features
 
 ### Browser Control
@@ -106,25 +140,159 @@ 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.
 
-### Auto-Pair Feature
+### Auto-Connect + Auto-Pair
 
 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)
 
+**Auto-connect** and **Auto-pair** are enabled by default for a seamless setup. The extension badge shows status (ON/OFF).
+
+### Default Settings (Extension)
+
+| Setting | Default |
+|---------|---------|
+| Relay port | `8787` |
+| Auto-connect | `true` |
+| Auto-pair | `true` |
+| Require pairing token | `true` |
+| Pairing token | `null` (fetched on connect) |
+
+### Connection Flow (Extension Relay)
+
+1. Extension checks the discovery endpoint at `http://127.0.0.1:8787/config`.
+2. It learns the relay port and whether pairing is required.
+3. If pairing is required and Auto-pair is on, it fetches the token from `http://127.0.0.1:<relayPort>/pair`.
+4. It connects to `ws://127.0.0.1:<relayPort>/extension` using the extension origin.
+
+`/config` and `/pair` are extension-origin only for CSWSH protection.
+
 ### 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
+
+### Where Extension Assets Live
+
+Extension assets are bundled inside the NPM package and extracted on install/startup:
+
+- Primary: `~/.config/opencode/opendevbrowser/extension`
+- Fallback: `~/.cache/opencode/node_modules/opendevbrowser/extension`
+
+Extraction is handled by `extractExtension()` (see `src/extension-extractor.ts`).
 
 ---
 
@@ -134,42 +302,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 +396,8 @@ rm -rf ~/.cache/opencode/node_modules/opendevbrowser
 npx opendevbrowser --update
 ```
 
-Release checklist: `docs/DISTRIBUTION_PLAN.md`
+Architecture overview: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+Release checklist: [docs/DISTRIBUTION_PLAN.md](docs/DISTRIBUTION_PLAN.md)
 
 ---
 
@@ -226,8 +409,24 @@ 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
 ```
 
+### Packaging & Distribution (NPM + GitHub + Extension)
+
+Uniform versioning is required (source of truth: `package.json`):
+
+1. Bump `package.json` version.
+2. Run: `npm run extension:sync`
+3. Run: `npm run version:check`
+4. Run: `npm run build`
+5. Run: `npm run extension:build`
+6. Run: `npm run extension:pack` (outputs `./opendevbrowser-extension.zip`)
+7. Publish to NPM and attach the zip to the GitHub release tag (`vX.Y.Z`).
+
+Release checklist: `docs/DISTRIBUTION_PLAN.md`
+
 ---
 
 ## Privacy