opendevbrowser 0.0.10

package/README.md

@@ -0,0 +1,241 @@
+# OpenDevBrowser
+
+[![npm version](https://img.shields.io/npm/v/opendevbrowser.svg?style=flat-square)](https://registry.npmjs.org/opendevbrowser)
+[![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)
+
+> **Script-first browser automation for AI agents.** Snapshot → Refs → Actions.
+
+OpenDevBrowser is an [OpenCode](https://opencode.ai) plugin that gives AI agents direct browser control via Chrome DevTools Protocol. Launch browsers, capture page snapshots, and interact with elements using stable refs.
+
+---
+
+## Installation
+
+### For Humans
+
+```bash
+# Interactive installer (recommended)
+npx opendevbrowser
+
+# Or specify location
+npx opendevbrowser --global   # ~/.config/opencode/opencode.json
+npx opendevbrowser --local    # ./opencode.json
+
+# Full install (config + extension assets)
+npx opendevbrowser --full
+```
+
+Restart OpenCode after installation.
+
+OpenCode discovers skills in `.opencode/skill` (project) and `~/.config/opencode/skill` (global) first; `.claude/skills` is compatibility-only. The CLI installs bundled skills into the OpenCode-native locations by default.
+
+### Agent Installation (OpenCode)
+
+Recommended (CLI, installs plugin + config + bundled skills + extension assets):
+
+```bash
+npx opendevbrowser --full --global --no-prompt
+```
+
+Manual fallback (edit OpenCode config):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opendevbrowser"]
+}
+```
+
+Config location: `~/.config/opencode/opencode.json`
+
+Restart OpenCode, then run `opendevbrowser_status` to verify the plugin is loaded.
+
+---
+
+## Quick Start
+
+```
+1. Launch a browser session
+2. Navigate to a URL
+3. Take a snapshot to get element refs
+4. Interact using refs (click, type, select)
+5. Re-snapshot after navigation
+```
+
+### Core Workflow
+
+| Step | Tool | Purpose |
+|------|------|---------|
+| 1 | `opendevbrowser_launch` | Start managed Chrome session |
+| 2 | `opendevbrowser_goto` | Navigate to URL |
+| 3 | `opendevbrowser_snapshot` | Get page structure with refs |
+| 4 | `opendevbrowser_click` / `opendevbrowser_type` | Interact with elements |
+| 5 | `opendevbrowser_close` | Clean up session |
+
+---
+
+## Features
+
+### Browser Control
+- **Launch & Connect** - Start managed Chrome or connect to existing browsers
+- **Multi-Tab Support** - Create, switch, and manage browser tabs
+- **Profile Persistence** - Maintain login sessions across runs
+- **Headless Mode** - Run without visible browser window
+
+### Page Interaction
+- **Snapshot** - Accessibility-tree based page capture (token-efficient)
+- **Click** - Click elements by ref
+- **Type** - Enter text into inputs
+- **Select** - Choose dropdown options
+- **Scroll** - Scroll page or elements
+- **Wait** - Wait for selectors or navigation
+
+### DevTools Integration
+- **Console Capture** - Monitor console.log, errors, warnings
+- **Network Tracking** - Capture XHR/fetch requests and responses
+- **Screenshot** - Full page or element screenshots
+- **Performance** - Page load metrics
+
+### Export & Clone
+- **DOM Capture** - Extract sanitized HTML with inline styles
+- **React Emitter** - Generate React component code from pages
+- **CSS Extraction** - Pull computed styles
+
+---
+
+## Chrome Extension (Optional)
+
+The extension enables **Mode C** - attach to existing logged-in browser tabs without launching a new browser.
+
+### Auto-Pair Feature
+
+The plugin and extension can automatically pair:
+
+1. **Plugin side**: Auto-generates secure token on first run (saved to config)
+2. **Extension side**: Enable "Auto-Pair" toggle and click Connect
+3. Extension fetches token from plugin's 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
+
+---
+
+## Configuration
+
+Optional config file: `~/.config/opencode/opendevbrowser.jsonc`
+
+```jsonc
+{
+  "headless": false,
+  "profile": "default",
+  "persistProfile": true,
+  "snapshot": { "maxChars": 16000, "maxNodes": 1000 },
+  "export": { "maxNodes": 1000, "inlineStyles": true },
+  "devtools": { "showFullUrls": false, "showFullConsole": false },
+  "security": {
+    "allowRawCDP": false,
+    "allowNonLocalCdp": false,
+    "allowUnsafeExport": false
+  },
+  "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"
+      ],
+      "maxAgeMs": 60000
+    }
+  },
+  "relayPort": 8787,
+  "relayToken": "auto-generated-on-first-run"
+}
+```
+
+All fields optional. Plugin works with sensible defaults.
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx opendevbrowser` | Interactive install |
+| `npx opendevbrowser --global` | Install to global config |
+| `npx opendevbrowser --local` | Install to project config |
+| `npx opendevbrowser --with-config` | Also create opendevbrowser.jsonc |
+| `npx opendevbrowser --full` | Full install (config + extension assets) |
+| `npx opendevbrowser --update` | Clear cache, trigger reinstall |
+| `npx opendevbrowser --uninstall` | Remove from config |
+| `npx opendevbrowser --version` | Show version |
+
+---
+
+## Security
+
+- **Relay Authentication** - Cryptographically secure tokens, timing-safe comparison
+- **Origin Validation** - Only localhost and Chrome extensions can pair
+- **CDP Localhost-Only** - Remote CDP endpoints blocked by default
+- **Data Redaction** - Console/network output redacts tokens and API keys
+- **Export Sanitization** - Scripts and event handlers stripped from exports
+- **Atomic Config Writes** - Prevents config corruption on crash
+
+---
+
+## Updating
+
+```bash
+# Option 1: Clear cache (recommended)
+rm -rf ~/.cache/opencode/node_modules/opendevbrowser
+# Then restart OpenCode
+
+# Option 2: Use CLI
+npx opendevbrowser --update
+```
+
+Release checklist: `docs/DISTRIBUTION_PLAN.md`
+
+---
+
+## Development
+
+```bash
+npm install
+npm run build      # Compile to dist/
+npm run test       # Run tests with coverage
+npm run lint       # ESLint checks
+npm run extension:build  # Compile extension
+```
+
+---
+
+## Privacy
+
+See [Privacy Policy](docs/privacy.md) for data handling details.
+
+---
+
+## License
+
+MIT

package/dist/chunk-R5VUZEUU.js

@@ -0,0 +1,128 @@
+// src/extension-extractor.ts
+import { existsSync, mkdirSync, cpSync, readFileSync, writeFileSync, rmSync, renameSync } from "fs";
+import { dirname, join } from "path";
+import { homedir } from "os";
+import { fileURLToPath } from "url";
+var EXTENSION_DIR_NAME = "opendevbrowser";
+var VERSION_FILE = ".version";
+function getConfigDir() {
+  return join(homedir(), ".config", "opencode", EXTENSION_DIR_NAME, "extension");
+}
+function getPackageVersion() {
+  try {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    return pkg.version || "0.0.0";
+  } catch (error) {
+    console.warn("[opendevbrowser] Failed to read package.json for extension version:", error);
+    return "0.0.0";
+  }
+}
+function getInstalledVersion(destDir) {
+  try {
+    const versionPath = join(destDir, VERSION_FILE);
+    if (existsSync(versionPath)) {
+      return readFileSync(versionPath, "utf-8").trim();
+    }
+  } catch (error) {
+    console.warn("[opendevbrowser] Failed to read installed extension version:", error);
+  }
+  return null;
+}
+function getBundledExtensionPath() {
+  const candidates = [
+    join(dirname(fileURLToPath(import.meta.url)), "..", "extension"),
+    join(dirname(fileURLToPath(import.meta.url)), "..", "..", "extension")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(join(candidate, "manifest.json"))) {
+      return candidate;
+    }
+  }
+  return null;
+}
+function isCompleteInstall(dir) {
+  const required = ["manifest.json", VERSION_FILE];
+  return required.every((file) => existsSync(join(dir, file)));
+}
+function extractExtension() {
+  const bundledPath = getBundledExtensionPath();
+  if (!bundledPath) {
+    return null;
+  }
+  const destDir = getConfigDir();
+  const currentVersion = getPackageVersion();
+  const installedVersion = getInstalledVersion(destDir);
+  if (installedVersion === currentVersion && isCompleteInstall(destDir)) {
+    return destDir;
+  }
+  const parentDir = dirname(destDir);
+  const stagingDir = join(parentDir, `.opendevbrowser-staging-${process.pid}-${Date.now()}`);
+  const backupDir = join(parentDir, `.opendevbrowser-backup-${process.pid}-${Date.now()}`);
+  try {
+    mkdirSync(stagingDir, { recursive: true });
+    const itemsToCopy = ["manifest.json", "popup.html", "dist", "icons"];
+    for (const item of itemsToCopy) {
+      const src = join(bundledPath, item);
+      const dest = join(stagingDir, item);
+      if (existsSync(src)) {
+        cpSync(src, dest, { recursive: true, force: true });
+      }
+    }
+    writeFileSync(join(stagingDir, VERSION_FILE), currentVersion, "utf-8");
+    if (!isCompleteInstall(stagingDir)) {
+      throw new Error("Staging directory incomplete after copy");
+    }
+    if (existsSync(destDir)) {
+      renameSync(destDir, backupDir);
+    }
+    renameSync(stagingDir, destDir);
+    if (existsSync(backupDir)) {
+      rmSync(backupDir, { recursive: true, force: true });
+    }
+    return destDir;
+  } catch (error) {
+    if (existsSync(backupDir) && !existsSync(destDir)) {
+      try {
+        renameSync(backupDir, destDir);
+      } catch (rollbackError) {
+        console.warn(`[opendevbrowser] Warning: Rollback failed for ${backupDir}:`, rollbackError);
+      }
+    }
+    if (existsSync(stagingDir)) {
+      try {
+        rmSync(stagingDir, { recursive: true, force: true });
+      } catch (stagingCleanupError) {
+        console.warn(`[opendevbrowser] Warning: Failed to clean up staging directory ${stagingDir}:`, stagingCleanupError);
+      }
+    }
+    if (existsSync(backupDir)) {
+      try {
+        rmSync(backupDir, { recursive: true, force: true });
+      } catch (backupCleanupError) {
+        console.warn(`[opendevbrowser] Warning: Failed to clean up backup directory ${backupDir}:`, backupCleanupError);
+      }
+    }
+    throw error;
+  }
+}
+function getExtensionPath() {
+  const destDir = getConfigDir();
+  if (isCompleteInstall(destDir)) {
+    return destDir;
+  }
+  return getBundledExtensionPath();
+}
+
+// src/utils/crypto.ts
+import { randomBytes } from "crypto";
+function generateSecureToken() {
+  return randomBytes(32).toString("hex");
+}
+
+export {
+  generateSecureToken,
+  extractExtension,
+  getExtensionPath
+};
+//# sourceMappingURL=chunk-R5VUZEUU.js.map

package/dist/chunk-R5VUZEUU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/extension-extractor.ts","../src/utils/crypto.ts"],"sourcesContent":["import { existsSync, mkdirSync, cpSync, readFileSync, writeFileSync, rmSync, renameSync } from \"fs\";\nimport { dirname, join } from \"path\";\nimport { homedir } from \"os\";\nimport { fileURLToPath } from \"url\";\n\nconst EXTENSION_DIR_NAME = \"opendevbrowser\";\nconst VERSION_FILE = \".version\";\n\nfunction getConfigDir(): string {\n  return join(homedir(), \".config\", \"opencode\", EXTENSION_DIR_NAME, \"extension\");\n}\n\nfunction getPackageVersion(): string {\n  try {\n    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), \"..\", \"package.json\");\n    const pkg = JSON.parse(readFileSync(pkgPath, \"utf-8\"));\n    return pkg.version || \"0.0.0\";\n  } catch (error) {\n    console.warn(\"[opendevbrowser] Failed to read package.json for extension version:\", error);\n    return \"0.0.0\";\n  }\n}\n\nfunction getInstalledVersion(destDir: string): string | null {\n  try {\n    const versionPath = join(destDir, VERSION_FILE);\n    if (existsSync(versionPath)) {\n      return readFileSync(versionPath, \"utf-8\").trim();\n    }\n  } catch (error) {\n    console.warn(\"[opendevbrowser] Failed to read installed extension version:\", error);\n  }\n  return null;\n}\n\nfunction getBundledExtensionPath(): string | null {\n  const candidates = [\n    join(dirname(fileURLToPath(import.meta.url)), \"..\", \"extension\"),\n    join(dirname(fileURLToPath(import.meta.url)), \"..\", \"..\", \"extension\")\n  ];\n  for (const candidate of candidates) {\n    if (existsSync(join(candidate, \"manifest.json\"))) {\n      return candidate;\n    }\n  }\n  return null;\n}\n\nfunction isCompleteInstall(dir: string): boolean {\n  const required = [\"manifest.json\", VERSION_FILE];\n  return required.every(file => existsSync(join(dir, file)));\n}\n\nexport function extractExtension(): string | null {\n  const bundledPath = getBundledExtensionPath();\n  if (!bundledPath) {\n    return null;\n  }\n\n  const destDir = getConfigDir();\n  const currentVersion = getPackageVersion();\n  const installedVersion = getInstalledVersion(destDir);\n\n  // Early return if version matches and installation is complete\n  if (installedVersion === currentVersion && isCompleteInstall(destDir)) {\n    return destDir;\n  }\n\n  // Create staging directory (sibling to destDir for same-device rename)\n  const parentDir = dirname(destDir);\n  const stagingDir = join(parentDir, `.opendevbrowser-staging-${process.pid}-${Date.now()}`);\n  const backupDir = join(parentDir, `.opendevbrowser-backup-${process.pid}-${Date.now()}`);\n\n  try {\n    // Step 1: Copy to staging\n    mkdirSync(stagingDir, { recursive: true });\n    const itemsToCopy = [\"manifest.json\", \"popup.html\", \"dist\", \"icons\"];\n    for (const item of itemsToCopy) {\n      const src = join(bundledPath, item);\n      const dest = join(stagingDir, item);\n      if (existsSync(src)) {\n        cpSync(src, dest, { recursive: true, force: true });\n      }\n    }\n    writeFileSync(join(stagingDir, VERSION_FILE), currentVersion, \"utf-8\");\n\n    // Step 2: Validate staging is complete\n    if (!isCompleteInstall(stagingDir)) {\n      throw new Error(\"Staging directory incomplete after copy\");\n    }\n\n    // Step 3: Atomic swap\n    if (existsSync(destDir)) {\n      renameSync(destDir, backupDir);\n    }\n    renameSync(stagingDir, destDir);\n\n    // Step 4: Cleanup backup\n    if (existsSync(backupDir)) {\n      rmSync(backupDir, { recursive: true, force: true });\n    }\n\n    return destDir;\n  } catch (error) {\n    // Rollback: restore backup if it exists\n    if (existsSync(backupDir) && !existsSync(destDir)) {\n      try {\n        renameSync(backupDir, destDir);\n      } catch (rollbackError) {\n        console.warn(`[opendevbrowser] Warning: Rollback failed for ${backupDir}:`, rollbackError);\n      }\n    }\n    // Cleanup staging\n    if (existsSync(stagingDir)) {\n      try {\n        rmSync(stagingDir, { recursive: true, force: true });\n      } catch (stagingCleanupError) {\n        console.warn(`[opendevbrowser] Warning: Failed to clean up staging directory ${stagingDir}:`, stagingCleanupError);\n      }\n    }\n    // Cleanup backup\n    if (existsSync(backupDir)) {\n      try {\n        rmSync(backupDir, { recursive: true, force: true });\n      } catch (backupCleanupError) {\n        console.warn(`[opendevbrowser] Warning: Failed to clean up backup directory ${backupDir}:`, backupCleanupError);\n      }\n    }\n    throw error;\n  }\n}\n\nexport function getExtensionPath(): string | null {\n  const destDir = getConfigDir();\n  if (isCompleteInstall(destDir)) {\n    return destDir;\n  }\n  return getBundledExtensionPath();\n}\n","import { randomBytes } from \"crypto\";\n\nexport function generateSecureToken(): string {\n  return randomBytes(32).toString(\"hex\");\n}\n"],"mappings":"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","names":[]}

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node