browserwire 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 GearSec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# BrowserWire
+
+A contract layer between AI agents and websites. BrowserWire auto-discovers typed browser APIs from live pages so agents never touch the DOM directly — they call versioned, validated, scoped operations like `open_ticket(id: "1234")` through a manifest that defines what exists, what's callable, and how to find targets.
+
+## How it works
+
+```
+Chrome Extension (discovers)     CLI Backend (builds manifest)     REST API (serves)
+┌─────────────────────────┐     ┌──────────────────────────┐     ┌──────────────────┐
+│ Content script scans    │────▶│ Vision LLM perceives     │────▶│ GET /api/sites   │
+│ page skeleton +         │ WS  │ entities & actions        │     │ GET /api/sites/  │
+│ screenshot annotation   │     │ Locator synthesis         │     │   :slug/docs     │
+│                         │◀────│ Manifest compilation      │     │ POST execute     │
+│ Sidepanel UI shows      │     │ Checkpoint merging        │     │                  │
+│ discovered API          │     │                           │     │                  │
+└─────────────────────────┘     └──────────────────────────┘     └──────────────────┘
+```
+
+1. **Extension** runs a skeleton scan on each page, captures an annotated screenshot, and sends both to the CLI backend over WebSocket
+2. **CLI** uses a vision LLM to perceive entities and actions from the screenshot + skeleton, synthesizes locators, and compiles a typed `BrowserWireManifest`
+3. **REST API** serves the discovered manifests so agents can query available actions and execute them
+
+## Quick start
+
+```bash
+# Install dependencies
+npm install
+
+# Configure your LLM provider
+cp .env.example .env
+# Edit .env with your API key and preferred provider
+
+# Load the Chrome extension
+# 1. Open chrome://extensions
+# 2. Enable "Developer mode"
+# 3. Click "Load unpacked" → select the extension/ directory
+
+# Start the CLI server
+npm run cli:dev
+
+# Browse to any site, click "Start Exploring" in the BrowserWire sidepanel
+# The CLI will discover and build a manifest for the site
+
+# View discovered APIs
+open http://localhost:8787/api/sites
+```
+
+## Extension permissions
+
+BrowserWire requires the `<all_urls>` permission because it needs to inspect whatever site the user navigates to during discovery. The extension only activates when you explicitly start an exploration session — it does not run in the background or send data anywhere except the local CLI server.
+
+## Project structure
+
+| Directory | Description |
+|-----------|-------------|
+| `cli/` | Node.js CLI server — WebSocket handler, discovery pipeline, REST API |
+| `cli/discovery/` | Discovery stages: perception, locator synthesis, compilation, enrichment |
+| `cli/api/` | REST API router and bridge to discovery sessions |
+| `extension/` | Chrome extension — content script, background worker, sidepanel UI |
+| `extension/shared/` | Shared protocol definitions (message types, envelopes) |
+| `src/contract-dsl/` | TypeScript contract DSL — manifest types, validation, compatibility, migration |
+| `tests/` | Test suite (vitest) |
+| `docs/` | Documentation — architecture (implemented subsystems) and design (speculative) |
+
+## Configuration
+
+BrowserWire uses environment variables for LLM configuration. Copy `.env.example` to `.env` and configure:
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `BROWSERWIRE_LLM_PROVIDER` | LLM provider: `openai`, `anthropic`, `gemini`, `ollama` | Yes |
+| `BROWSERWIRE_LLM_API_KEY` | API key for the provider | Yes (except ollama) |
+| `BROWSERWIRE_LLM_MODEL` | Model name (default varies by provider) | No |
+| `BROWSERWIRE_LLM_BASE_URL` | Custom endpoint URL (for ollama or proxies) | No |
+
+### Provider defaults
+
+| Provider | Default model | Default endpoint |
+|----------|--------------|-----------------|
+| `openai` | `gpt-4o` | `https://api.openai.com/v1` |
+| `anthropic` | `claude-sonnet-4-20250514` | `https://api.anthropic.com` |
+| `gemini` | `gemini-2.5-flash` | `https://generativelanguage.googleapis.com/v1beta/openai` |
+| `ollama` | `llama3` | `http://localhost:11434` |
+
+## API usage
+
+Once the CLI server is running and you've explored a site:
+
+```bash
+# List all discovered sites
+curl http://localhost:8787/api/sites
+
+# Get the manifest/docs for a specific site
+curl http://localhost:8787/api/sites/example-com/docs
+
+# Execute an action (via the extension bridge)
+curl -X POST http://localhost:8787/api/sites/example-com/execute \
+  -H "Content-Type: application/json" \
+  -d '{"actionId": "action_submit_login", "inputs": {"email": "user@example.com"}}'
+```
+
+## Contributing
+
+PRs welcome! Please run tests before submitting:
+
+```bash
+npm test
+npm run typecheck
+```
+
+## License
+
+[MIT](LICENSE)

package/cli/api/bridge.js

@@ -0,0 +1,64 @@
+/**
+ * bridge.js — HTTP-to-WebSocket request/response bridge
+ *
+ * Mirrors the request-response pattern from the old SDK runtime.
+ * Each HTTP request gets a unique requestId, sends a WS message,
+ * and awaits a matching response.
+ */
+
+import { createEnvelope } from "../../extension/shared/protocol.js";
+
+const DEFAULT_TIMEOUT_MS = 30000;
+
+export const createBridge = () => {
+  /** @type {Map<string, { resolve: Function, reject: Function, timer: ReturnType<typeof setTimeout> }>} */
+  const pending = new Map();
+
+  /**
+   * Send a WS message and await a matching response by requestId.
+   */
+  const sendAndAwait = (socket, type, payload, timeoutMs = DEFAULT_TIMEOUT_MS) =>
+    new Promise((resolve, reject) => {
+      if (!socket || socket.readyState !== 1) {
+        reject(new Error("Extension not connected"));
+        return;
+      }
+
+      const requestId = crypto.randomUUID();
+
+      const timer = setTimeout(() => {
+        pending.delete(requestId);
+        reject(new Error(`Request ${type} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+
+      pending.set(requestId, { resolve, reject, timer });
+      socket.send(JSON.stringify(createEnvelope(type, payload, requestId)));
+    });
+
+  /**
+   * Check if an incoming WS message matches a pending request.
+   * Returns true if it was consumed.
+   */
+  const handleWsResult = (message) => {
+    if (!message.requestId || !pending.has(message.requestId)) return false;
+
+    const req = pending.get(message.requestId);
+    pending.delete(message.requestId);
+    clearTimeout(req.timer);
+    req.resolve(message.payload);
+    return true;
+  };
+
+  /**
+   * Reject all pending requests (e.g. on disconnect).
+   */
+  const rejectAll = (reason) => {
+    for (const [, req] of pending) {
+      clearTimeout(req.timer);
+      req.reject(new Error(reason));
+    }
+    pending.clear();
+  };
+
+  return { sendAndAwait, handleWsResult, rejectAll };
+};

package/cli/api/openapi.js

@@ -0,0 +1,175 @@
+/**
+ * openapi.js — OpenAPI 3.0.3 spec generator from BrowserWire manifests
+ */
+
+const sanitizeName = (name) =>
+  (name || "unknown")
+    .toLowerCase()
+    .replace(/[^a-z0-9_]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+
+const inputsToSchema = (inputs) => {
+  if (!inputs || inputs.length === 0) return null;
+  const properties = {};
+  for (const input of inputs) {
+    properties[input.name] = {
+      type: input.type || "string",
+      description: input.description || ""
+    };
+  }
+  return { type: "object", properties };
+};
+
+export const generateOpenApiSpec = (manifest, { host = "127.0.0.1", port = 8787, pathPrefix = "" } = {}) => {
+  const actions = manifest.actions || [];
+  const views = manifest.views || [];
+  const workflows = manifest.workflowActions || [];
+  const entities = manifest.entities || [];
+
+  const paths = {};
+
+  // Manifest endpoint
+  paths[`${pathPrefix}/manifest`] = {
+    get: {
+      summary: "Raw manifest JSON",
+      operationId: "getManifest",
+      tags: ["System"],
+      responses: {
+        200: { description: "Full manifest", content: { "application/json": { schema: { type: "object" } } } }
+      }
+    }
+  };
+
+  // Actions
+  for (const action of actions) {
+    const name = sanitizeName(action.semanticName || action.name);
+    const path = `${pathPrefix}/actions/${name}`;
+    const bodySchema = inputsToSchema(action.inputs);
+
+    paths[path] = {
+      post: {
+        summary: action.description || action.name,
+        operationId: `action_${name}`,
+        tags: ["Actions"],
+        ...(bodySchema ? {
+          requestBody: {
+            required: true,
+            content: { "application/json": { schema: bodySchema } }
+          }
+        } : {}),
+        responses: {
+          200: {
+            description: "Action result",
+            content: { "application/json": { schema: {
+              type: "object",
+              properties: {
+                ok: { type: "boolean" },
+                result: { type: "object" },
+                error: { type: "string" }
+              }
+            }}}
+          }
+        }
+      }
+    };
+  }
+
+  // Views
+  for (const view of views) {
+    const name = sanitizeName(view.semanticName || view.name);
+    const path = `${pathPrefix}/views/${name}`;
+
+    paths[path] = {
+      get: {
+        summary: view.description || view.name,
+        operationId: `view_${name}`,
+        tags: ["Views"],
+        responses: {
+          200: {
+            description: "View data",
+            content: { "application/json": { schema: {
+              type: "object",
+              properties: {
+                ok: { type: "boolean" },
+                data: view.isList ? { type: "array", items: { type: "object" } } : { type: "object" },
+                count: { type: "integer" }
+              }
+            }}}
+          }
+        }
+      }
+    };
+  }
+
+  // Workflows
+  for (const workflow of workflows) {
+    const name = sanitizeName(workflow.name);
+    const path = `${pathPrefix}/workflows/${name}`;
+    const bodySchema = inputsToSchema(workflow.inputs);
+
+    paths[path] = {
+      post: {
+        summary: workflow.description || workflow.name,
+        operationId: `workflow_${name}`,
+        tags: ["Workflows"],
+        ...(bodySchema ? {
+          requestBody: {
+            required: true,
+            content: { "application/json": { schema: bodySchema } }
+          }
+        } : {}),
+        responses: {
+          200: {
+            description: "Workflow result",
+            content: { "application/json": { schema: {
+              type: "object",
+              properties: {
+                ok: { type: "boolean" },
+                data: { type: "object" },
+                outcome: { type: "string" },
+                error: { type: "string" }
+              }
+            }}}
+          }
+        }
+      }
+    };
+  }
+
+  // Entities
+  for (const entity of entities) {
+    const name = sanitizeName(entity.semanticName || entity.name);
+    const path = `${pathPrefix}/entities/${name}`;
+
+    paths[path] = {
+      get: {
+        summary: `Read state of ${entity.semanticName || entity.name}`,
+        operationId: `entity_${name}`,
+        tags: ["Entities"],
+        responses: {
+          200: {
+            description: "Entity state",
+            content: { "application/json": { schema: {
+              type: "object",
+              properties: {
+                ok: { type: "boolean" },
+                state: { type: "object" }
+              }
+            }}}
+          }
+        }
+      }
+    };
+  }
+
+  return {
+    openapi: "3.0.3",
+    info: {
+      title: `BrowserWire API — ${manifest.domain || "Unknown"}`,
+      description: manifest.domainDescription || "Auto-discovered browser API",
+      version: manifest.manifestVersion || "1.0.0"
+    },
+    servers: [{ url: `http://${host}:${port}` }],
+    paths
+  };
+};

package/cli/api/router.js

@@ -0,0 +1,280 @@
+/**
+ * router.js — Lightweight HTTP router for the BrowserWire REST API
+ *
+ * All operational routes live under /api/sites/:slug/...
+ * No implicit "active site" concept.
+ */
+
+import { MessageType } from "../../extension/shared/protocol.js";
+import { generateOpenApiSpec } from "./openapi.js";
+import { swaggerUiHtml } from "./swagger-ui.js";
+
+const CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type"
+};
+
+const json = (res, status, body) => {
+  const data = JSON.stringify(body);
+  res.writeHead(status, { ...CORS_HEADERS, "Content-Type": "application/json" });
+  res.end(data);
+};
+
+const html = (res, status, body) => {
+  res.writeHead(status, { ...CORS_HEADERS, "Content-Type": "text/html" });
+  res.end(body);
+};
+
+const readBody = (req) =>
+  new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => {
+      try {
+        const raw = Buffer.concat(chunks).toString();
+        resolve(raw.length > 0 ? JSON.parse(raw) : {});
+      } catch {
+        reject(new Error("Invalid JSON body"));
+      }
+    });
+    req.on("error", reject);
+  });
+
+/**
+ * Build name->definition lookup maps from a manifest.
+ */
+const buildLookups = (manifest) => {
+  const actionMap = new Map();
+  for (const action of manifest.actions || []) {
+    const name = sanitize(action.semanticName || action.name);
+    actionMap.set(name, action);
+  }
+
+  const viewMap = new Map();
+  for (const view of manifest.views || []) {
+    const name = sanitize(view.semanticName || view.name);
+    viewMap.set(name, view);
+  }
+
+  const workflowMap = new Map();
+  for (const workflow of manifest.workflowActions || []) {
+    const name = sanitize(workflow.name);
+    workflowMap.set(name, workflow);
+  }
+
+  const entityMap = new Map();
+  for (const entity of manifest.entities || []) {
+    const name = sanitize(entity.semanticName || entity.name);
+    entityMap.set(name, entity);
+  }
+
+  return { actionMap, viewMap, workflowMap, entityMap };
+};
+
+const sanitize = (name) =>
+  (name || "unknown")
+    .toLowerCase()
+    .replace(/[^a-z0-9_]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+
+/**
+ * Render an HTML landing page listing all known sites with links to their docs.
+ */
+const landingPageHtml = (sites, host, port) => {
+  const rows = sites.map((s) => {
+    const docsUrl = `/api/sites/${s.slug}/docs`;
+    return `<tr>
+      <td><a href="${docsUrl}">${s.slug}</a></td>
+      <td>${s.origin}</td>
+      <td>${s.entityCount || 0}</td>
+      <td>${s.actionCount || 0}</td>
+      <td>${s.viewCount || 0}</td>
+    </tr>`;
+  }).join("\n");
+
+  return `<!DOCTYPE html>
+<html><head><title>BrowserWire API</title>
+<style>
+  body { font-family: system-ui, sans-serif; max-width: 800px; margin: 40px auto; padding: 0 20px; }
+  table { border-collapse: collapse; width: 100%; margin-top: 20px; }
+  th, td { text-align: left; padding: 8px 12px; border-bottom: 1px solid #ddd; }
+  th { background: #f5f5f5; }
+  a { color: #0066cc; }
+  .empty { color: #888; margin-top: 20px; }
+</style></head>
+<body>
+  <h1>BrowserWire API</h1>
+  ${sites.length > 0 ? `<table>
+    <thead><tr><th>Site</th><th>Origin</th><th>Entities</th><th>Actions</th><th>Views</th></tr></thead>
+    <tbody>${rows}</tbody>
+  </table>` : `<p class="empty">No sites discovered yet. Run discovery from the browser extension to get started.</p>`}
+</body></html>`;
+};
+
+/**
+ * Create the HTTP request handler.
+ *
+ * @param {{ getManifestBySlug: (slug: string) => object|null, listSites: () => Array, bridge: object, getSocket: () => WebSocket|null, host: string, port: number }} deps
+ * @returns {(req: import("http").IncomingMessage, res: import("http").ServerResponse) => void}
+ */
+export const createHttpHandler = ({ getManifestBySlug, listSites, bridge, getSocket, host, port }) => {
+  return async (req, res) => {
+    // CORS preflight
+    if (req.method === "OPTIONS") {
+      res.writeHead(204, CORS_HEADERS);
+      res.end();
+      return;
+    }
+
+    const url = new URL(req.url, `http://${req.headers.host || "localhost"}`);
+    const path = url.pathname;
+
+    // ── System routes ──
+
+    if (path === "/api/health" && req.method === "GET") {
+      const socket = getSocket();
+      return json(res, 200, {
+        ok: true,
+        extensionConnected: socket !== null && socket.readyState === 1
+      });
+    }
+
+    if (path === "/api/sites" && req.method === "GET") {
+      const sites = listSites();
+      return json(res, 200, { ok: true, sites });
+    }
+
+    // ── Landing page listing all sites ──
+
+    if (path === "/api/docs" && req.method === "GET") {
+      const sites = listSites();
+      return html(res, 200, landingPageHtml(sites, host, port));
+    }
+
+    // ── Site-scoped routes: /api/sites/:slug/... ──
+
+    const siteMatch = path.match(/^\/api\/sites\/([^/]+)(\/.*)?$/);
+    if (siteMatch) {
+      const slug = siteMatch[1];
+      const subPath = siteMatch[2] || "";
+
+      const manifest = getManifestBySlug(slug);
+      if (!manifest) {
+        return json(res, 404, { ok: false, error: `No manifest found for site '${slug}'` });
+      }
+
+      // GET /api/sites/:slug/manifest
+      if (subPath === "/manifest" && req.method === "GET") {
+        return json(res, 200, manifest);
+      }
+
+      // GET /api/sites/:slug/openapi.json
+      if (subPath === "/openapi.json" && req.method === "GET") {
+        return json(res, 200, generateOpenApiSpec(manifest, { host, port, pathPrefix: `/api/sites/${slug}` }));
+      }
+
+      // GET /api/sites/:slug/docs
+      if (subPath === "/docs" && req.method === "GET") {
+        return html(res, 200, swaggerUiHtml(`/api/sites/${slug}/openapi.json`));
+      }
+
+      // Routes below require an extension connection
+      const socket = getSocket();
+      if (!socket || socket.readyState !== 1) {
+        return json(res, 503, { ok: false, error: "Extension not connected" });
+      }
+
+      const lookups = buildLookups(manifest);
+
+      // POST /api/sites/:slug/actions/:name
+      const actionMatch = subPath.match(/^\/actions\/([^/]+)$/);
+      if (actionMatch && req.method === "POST") {
+        const action = lookups.actionMap.get(actionMatch[1]);
+        if (!action) return json(res, 404, { ok: false, error: `Action '${actionMatch[1]}' not found` });
+
+        let body = {};
+        try { body = await readBody(req); } catch { return json(res, 400, { ok: false, error: "Invalid JSON body" }); }
+
+        try {
+          const result = await bridge.sendAndAwait(socket, MessageType.EXECUTE_ACTION, {
+            actionId: action.id,
+            strategies: action.locatorSet?.strategies || [],
+            interactionKind: action.interactionKind || "click",
+            inputs: body
+          }, 30000);
+          return json(res, 200, result);
+        } catch (err) {
+          return json(res, 500, { ok: false, error: err.message });
+        }
+      }
+
+      // GET /api/sites/:slug/views/:name
+      const viewMatch = subPath.match(/^\/views\/([^/]+)$/);
+      if (viewMatch && req.method === "GET") {
+        const view = lookups.viewMap.get(viewMatch[1]);
+        if (!view) return json(res, 404, { ok: false, error: `View '${viewMatch[1]}' not found` });
+
+        try {
+          const result = await bridge.sendAndAwait(socket, MessageType.READ_ENTITY, {
+            viewId: view.id,
+            containerLocator: view.containerLocator?.strategies || [],
+            itemLocator: view.itemLocator || null,
+            fields: view.fields || [],
+            isList: view.isList || false
+          }, 30000);
+          return json(res, 200, result);
+        } catch (err) {
+          return json(res, 500, { ok: false, error: err.message });
+        }
+      }
+
+      // POST /api/sites/:slug/workflows/:name
+      const workflowMatch = subPath.match(/^\/workflows\/([^/]+)$/);
+      if (workflowMatch && req.method === "POST") {
+        const workflow = lookups.workflowMap.get(workflowMatch[1]);
+        if (!workflow) return json(res, 404, { ok: false, error: `Workflow '${workflowMatch[1]}' not found` });
+
+        let body = {};
+        try { body = await readBody(req); } catch { return json(res, 400, { ok: false, error: "Invalid JSON body" }); }
+
+        try {
+          const result = await bridge.sendAndAwait(socket, MessageType.EXECUTE_WORKFLOW, {
+            steps: workflow.steps || [],
+            outcomes: workflow.outcomes || {},
+            inputs: body
+          }, 60000);
+          return json(res, 200, result);
+        } catch (err) {
+          return json(res, 500, { ok: false, error: err.message });
+        }
+      }
+
+      // GET /api/sites/:slug/entities/:name
+      const entityMatch = subPath.match(/^\/entities\/([^/]+)$/);
+      if (entityMatch && req.method === "GET") {
+        const entity = lookups.entityMap.get(entityMatch[1]);
+        if (!entity) return json(res, 404, { ok: false, error: `Entity '${entityMatch[1]}' not found` });
+
+        const entityAction = (manifest.actions || []).find((a) => a.entityId === entity.id);
+        const strategies = entityAction?.locatorSet?.strategies || [];
+
+        try {
+          const result = await bridge.sendAndAwait(socket, MessageType.READ_ENTITY, {
+            entityId: entity.id,
+            strategies
+          }, 30000);
+          return json(res, 200, result);
+        } catch (err) {
+          return json(res, 500, { ok: false, error: err.message });
+        }
+      }
+
+      // Unknown sub-path under a valid site
+      return json(res, 404, { ok: false, error: "Not found" });
+    }
+
+    // ── Fallback ──
+    json(res, 404, { ok: false, error: "Not found" });
+  };
+};

package/cli/api/swagger-ui.js

@@ -0,0 +1,26 @@
+/**
+ * swagger-ui.js — Returns an HTML string that renders Swagger UI
+ * pointing at the local OpenAPI spec. Zero npm dependencies.
+ */
+
+export const swaggerUiHtml = (specUrl = "/api/openapi.json") => `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>BrowserWire API Docs</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css" />
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+  <script>
+    SwaggerUIBundle({
+      url: "${specUrl}",
+      dom_id: "#swagger-ui",
+      presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset],
+      layout: "BaseLayout"
+    });
+  </script>
+</body>
+</html>`;