opera-browser-cli 0.1.27

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kun Chen
+
+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,316 @@
+<h1 align="center">opera-browser-cli</h1>
+
+<h3 align="center">The most agent-ergonomic browser automation</h3>
+
+`opera-browser-cli` is a fork of [chrome-devtools-axi](https://github.com/kunchenguid/chrome-devtools-axi).
+It wraps [opera-devtools-mcp](https://github.com/operasoftware/opera-devtools-mcp) with an [AXI](https://axi.md)-compliant CLI.
+
+- **Token-efficient** — TOON-encoded output cuts token usage ~40% vs raw JSON
+- **Combined operations** — one command navigates, captures, and suggests next steps
+- **Contextual suggestions** — every response includes actionable next-step hints
+
+## Quick Start
+
+```sh
+$ opera-browser-cli open https://example.com
+page: {title: "Example Domain", url: "https://example.com", refs: 1}
+snapshot:
+RootWebArea "Example Domain"
+  heading "Example Domain"
+  paragraph "This domain is for use in illustrative examples..."
+  uid=1 link "More information..."
+help[1]:
+  Run `opera-browser-cli click @1` to click the "More information..." link
+
+$ opera-browser-cli click @1
+page: {title: "IANA — IANA-Managed Reserved Domains", refs: 12}
+snapshot:
+...
+```
+
+## Install
+
+Prerequisites: **Node.js >= 20**, **Opera** browser ([Opera Neon](https://www.operaneon.com) recommended for AI features), **[opera-devtools-mcp](https://github.com/operasoftware/opera-devtools-mcp)**.
+
+### From source
+
+**1. Build and link `opera-devtools-mcp`:**
+
+```sh
+git clone https://github.com/operasoftware/opera-devtools-mcp
+cd opera-devtools-mcp
+npm install && npm run build && npm link
+```
+
+**2. Build and link `opera-browser-cli`:**
+
+```sh
+# in this repo
+npm install && npm run build && npm link
+```
+
+**3. Run first-time setup:**
+
+```sh
+opera-browser-cli setup
+```
+
+This detects Opera installations, lets you pick one, saves configuration to `~/.opera-browser-cli/config`, and installs the Claude Code skill to `~/.claude/skills/opera-browser-cli/SKILL.md`.
+
+Verify:
+
+```sh
+opera-browser-cli --version
+opera-browser-cli open https://example.com
+```
+
+### Usage examples
+
+```sh
+# Basic navigation
+opera-browser-cli open https://example.com
+
+# Use Opera as the browser
+OPERA_CLI_EXECUTABLE_PATH="/Applications/Opera.app/Contents/MacOS/Opera" \
+  opera-browser-cli open https://example.com
+
+# Headed mode (visible browser window)
+OPERA_CLI_HEADED=1 opera-browser-cli open https://example.com
+
+# Persistent profile (stay logged in across sessions)
+OPERA_CLI_USER_DATA_DIR=~/.opera-profile opera-browser-cli open https://example.com
+
+# Connect to already-running browser
+OPERA_CLI_BROWSER_URL=http://127.0.0.1:9222 opera-browser-cli open https://example.com
+```
+
+## How It Works
+
+```
+┌───────────────────────┐
+│  opera-browser-cli  │  CLI — parse args, format output
+└──────────┬────────────┘
+           │ HTTP (localhost:9224)
+           ▼
+┌───────────────────────┐
+│     Bridge Server     │  Persistent process, manages MCP session
+└──────────┬────────────┘
+           │ stdio
+           ▼
+┌───────────────────────┐
+│  opera-devtools-mcp  │  Headless Chrome via DevTools Protocol
+└───────────────────────┘
+```
+
+- **Persistent bridge** — a detached process keeps the MCP session alive across commands, so Chrome doesn't restart every invocation
+- **Auto-lifecycle** — the bridge starts on first command and writes a PID file to `~/.opera-browser-cli/bridge.pid`
+- **Snapshot parsing** — accessibility tree snapshots are extracted and analyzed for interactive elements (`uid=` refs)
+- **TOON encoding** — structured metadata uses [TOON format](https://www.npmjs.com/package/@toon-format/toon) for compact, token-efficient output
+
+## CLI Reference
+
+### Navigation
+
+| Command           | Description                                  |
+| ----------------- | -------------------------------------------- |
+| `open <url>`      | Navigate to URL and snapshot                 |
+| `snapshot`        | Capture current page state                   |
+| `screenshot <p>`  | Save a screenshot to a file                  |
+| `scroll <dir>`    | Scroll: up, down, top, bottom                |
+| `back`            | Navigate back                                |
+| `wait <ms\|text>` | Wait for time or text to appear              |
+| `eval <js>`       | Evaluate a JavaScript expression or function |
+| `run`             | Execute a multi-step script from stdin       |
+
+`eval` wraps plain input as `() => (<expr>)` before sending it to DevTools. For multi-statement logic, pass an arrow function, `function`, or IIFE yourself.
+
+```sh
+opera-browser-cli eval "document.title"
+opera-browser-cli eval "(() => { const rows = [...document.querySelectorAll('tr')]; return rows.map((row) => row.textContent) })()"
+```
+
+### Interaction
+
+| Command                    | Description                    |
+| -------------------------- | ------------------------------ |
+| `click @<uid>`             | Click an element by ref        |
+| `fill @<uid> <text>`       | Fill a form field              |
+| `type <text>`              | Type text at current focus     |
+| `press <key>`              | Press a keyboard key           |
+| `hover @<uid>`             | Hover over an element          |
+| `drag @<from> @<to>`       | Drag an element onto another   |
+| `fillform @<uid>=<val>...` | Fill multiple form fields      |
+| `dialog <accept\|dismiss>` | Handle a browser dialog        |
+| `upload @<uid> <path>`     | Upload a file through an input |
+
+### Page Management
+
+| Command           | Description                 |
+| ----------------- | --------------------------- |
+| `pages`           | List all open tabs          |
+| `newpage <url>`   | Open a new tab              |
+| `selectpage <id>` | Switch to a tab by ID       |
+| `closepage <id>`  | Close a tab by ID           |
+| `resize <w> <h>`  | Resize the browser viewport |
+
+### Emulation
+
+| Command   | Description                     |
+| --------- | ------------------------------- |
+| `emulate` | Emulate device/network/viewport |
+
+### DevTools Debugging
+
+| Command            | Description                    |
+| ------------------ | ------------------------------ |
+| `console`          | List console messages          |
+| `console-get <id>` | Get a specific console message |
+| `network`          | List network requests          |
+| `network-get [id]` | Get a specific network request |
+
+### Performance
+
+| Command                     | Description                   |
+| --------------------------- | ----------------------------- |
+| `lighthouse`                | Run a Lighthouse audit        |
+| `perf-start`                | Start a performance trace     |
+| `perf-stop`                 | Stop the performance trace    |
+| `perf-insight <set> <name>` | Analyze a performance insight |
+| `heap <path>`               | Capture a heap snapshot       |
+
+### Opera AI
+
+Requires Opera Neon with an active Opera account.
+
+| Command             | Description                                   |
+| ------------------- | --------------------------------------------- |
+| `chat <prompt>`     | Send a chat message to Opera's built-in AI    |
+| `invoke-do <prompt>`| Ask the AI to perform a complex browsing task |
+| `make <prompt>`     | Ask the AI to build a webpage or app          |
+| `research <prompt>` | Ask the AI to research a topic in depth       |
+
+`research` accepts `--type local` (default), `--type one-minute`, or `--type deep`.
+
+### Configuration
+
+| Command  | Description                                      |
+| -------- | ------------------------------------------------ |
+| `setup`  | Interactive first-time setup (browser path, etc) |
+| `doctor` | Check configuration and environment              |
+| `logs`   | Show bridge server logs                          |
+
+### Bridge
+
+| Command | Description             |
+| ------- | ----------------------- |
+| `start` | Start the bridge server |
+| `stop`  | Stop the bridge server  |
+
+Running with no command shows the CLI home view. It prepends `bin` and
+`description` metadata, then includes the current snapshot when a browser
+session is active or the no-session status/help block when one is not.
+
+### Flags
+
+| Flag                        | Description                                 |
+| --------------------------- | ------------------------------------------- |
+| `--help`                    | Show usage information                      |
+| `-v`, `-V`, `--version`     | Show the installed CLI version              |
+| `--full`                    | Show complete output without truncation     |
+| `--background`              | Open new page in background (newpage)       |
+| `--uid @<uid>`              | Target a specific element (screenshot)      |
+| `--full-page`               | Capture entire scrollable page (screenshot) |
+| `--format <fmt>`            | Image format: png, jpeg, webp (screenshot)  |
+| `--viewport <spec>`         | Viewport like "390x844x3,mobile" (emulate)  |
+| `--color-scheme <value>`    | dark, light, or auto (emulate)              |
+| `--network <condition>`     | Network throttle: Slow 3G, etc. (emulate)   |
+| `--cpu <rate>`              | CPU throttling rate 1-20 (emulate)          |
+| `--geolocation <lat>x<lon>` | Set geolocation (emulate)                   |
+| `--user-agent <string>`     | Custom user agent (emulate)                 |
+| `--type <type>`             | Filter by type (console, network)           |
+| `--limit <n>`               | Max items to return (console, network)      |
+| `--page <n>`                | Pagination (console, network)               |
+| `--device <device>`         | desktop or mobile (lighthouse)              |
+| `--mode <mode>`             | navigation or snapshot (lighthouse)         |
+| `--output-dir <path>`       | Directory for reports (lighthouse)          |
+| `--no-reload`               | Skip page reload (perf-start)               |
+| `--no-auto-stop`            | Disable auto-stop (perf-start)              |
+| `--file <path>`             | Save trace data to file (perf-start/stop)   |
+| `--response-file <path>`    | Save response body (network-get)            |
+| `--request-file <path>`     | Save request body (network-get)             |
+
+## Configuration
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `OPERA_CLI_PORT` | `9224` | Bridge server port |
+| `OPERA_CLI_MCP_BIN` | `opera-devtools-mcp` | MCP server binary |
+| `OPERA_CLI_EXECUTABLE_PATH` | _(system Chrome)_ | Custom browser binary |
+| `OPERA_CLI_BROWSER_URL` | — | Connect to an existing browser instance instead of launching one |
+| `OPERA_CLI_USER_DATA_DIR` | — | Persistent Chrome profile directory (skips isolated mode) |
+| `OPERA_CLI_HEADED` | — | Set to `1` to run in headed (visible) mode |
+| `OPERA_CLI_CHROME_ARGS` | — | Extra Chrome flags, space-separated |
+| `OPERA_CLI_DISABLE_HOOKS` | — | Set to `1` to skip auto-installing session hooks |
+
+State is stored in `~/.opera-browser-cli/`:
+
+| File         | Purpose                            |
+| ------------ | ---------------------------------- |
+| `bridge.pid` | PID and port of the running bridge |
+
+### Session Hooks
+
+On supported agents, the packaged CLI also installs a `SessionStart` hook in `~/.claude/settings.json` and `~/.codex/hooks.json`, and enables `codex_hooks` in `~/.codex/config.toml`.
+
+Set `OPERA_CLI_DISABLE_HOOKS=1` to skip that auto-install behavior.
+
+Development entrypoints such as `npm run dev` and `bin/opera-browser-cli.ts` do not modify those hook files.
+
+## Local Setup (Full Stack)
+
+Both `opera-devtools-mcp` and `opera-browser-cli` need to be built and linked so they're available in PATH.
+
+**1. Build and link `opera-devtools-mcp`:**
+
+```sh
+# in the opera-devtools-mcp repo
+npm install
+npm run build
+npm link
+```
+
+**2. Build and link `opera-browser-cli`:**
+
+```sh
+# in this repo
+npm install
+npm run build
+npm link
+```
+
+**3. Set the browser executable path:**
+
+```sh
+export OPERA_CLI_EXECUTABLE_PATH="/Applications/Opera Neon Developer.app/Contents/MacOS/Opera"
+```
+
+**Tip:** Set `OPERA_CLI_MCP_BIN` to point to the locally linked `opera-devtools-mcp`:
+
+```sh
+export OPERA_CLI_MCP_BIN=opera-devtools-mcp
+```
+
+**Tip:** Set `OPERA_CLI_HEADED=1` to launch the browser in headed (visible) mode — useful during development to watch what's happening:
+
+```sh
+export OPERA_CLI_HEADED=1
+```
+
+## Development
+
+```sh
+npm run build      # Compile TypeScript to dist/
+npm run dev        # Run CLI directly with tsx
+npm test           # Run tests with vitest
+npm run test:watch # Run tests in watch mode
+```

package/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: opera-browser-cli
+description: Browser automation and web interaction using the opera-browser-cli tool. Use for navigating pages, clicking elements, filling forms, taking screenshots, inspecting console/network, running performance audits, and Opera Neon AI features (chat, invoke-do, make, research) when Opera Neon is the active browser.
+---
+
+# Skill: opera-browser-cli Browser Automation
+
+`opera-browser-cli` controls a Opera browser browser session.
+
+- **Standard commands** (`open`, `click`, `fill`, `screenshot`, etc.) — work with any Opera browser session.
+- **Opera AI commands** (`chat`, `invoke-do`, `make`, `research`) — require **Opera Neon** with an active sign-in.
+
+Run `opera-browser-cli --help` for the full command list, or `opera-browser-cli <command> --help` for per-command flags and examples.
+
+```bash
+opera-browser-cli open https://example.com   # start here — navigate and snapshot the page
+```
+
+If a user hits `Opera Neon: user is not signed in` or wants to use AI commands, suggest they run `opera-browser-cli setup` (interactive wizard) and sign in to Opera Neon. Run `opera-browser-cli doctor` to diagnose configuration issues.

package/dist/bin/opera-browser-cli-bridge.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env tsx
+export {};

package/dist/bin/opera-browser-cli-bridge.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env tsx
+import { getErrorMessage, runBridge } from "../src/bridge.js";
+runBridge().catch((error) => {
+    process.stderr.write(`[opera-browser-cli] Fatal: ${getErrorMessage(error)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=opera-browser-cli-bridge.js.map

package/dist/bin/opera-browser-cli-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"opera-browser-cli-bridge.js","sourceRoot":"","sources":["../../bin/opera-browser-cli-bridge.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE9D,SAAS,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8BAA8B,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/bin/opera-browser-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/opera-browser-cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+main(process.argv.slice(2));
+//# sourceMappingURL=opera-browser-cli.js.map

package/dist/bin/opera-browser-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"opera-browser-cli.js","sourceRoot":"","sources":["../../bin/opera-browser-cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAErC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/bin/opera-cli-bridge.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env tsx
+export {};

package/dist/bin/opera-cli-bridge.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env tsx
+import { getErrorMessage, runBridge } from "../src/bridge.js";
+runBridge().catch((error) => {
+    process.stderr.write(`[opera-cli] Fatal: ${getErrorMessage(error)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=opera-cli-bridge.js.map

package/dist/bin/opera-cli-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"opera-cli-bridge.js","sourceRoot":"","sources":["../../bin/opera-cli-bridge.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE9D,SAAS,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,sBAAsB,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACvE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/bin/opera-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/opera-cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+main(process.argv.slice(2));
+//# sourceMappingURL=opera-cli.js.map

package/dist/bin/opera-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"opera-cli.js","sourceRoot":"","sources":["../../bin/opera-cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAErC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/src/bridge.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Persistent MCP bridge server for opera-browser-cli.
+ *
+ * Spawns opera-devtools-mcp as a child process and maintains a single
+ * persistent MCP session. Exposes a simple HTTP API:
+ *   POST /call  { name, args }  → { result }
+ *   GET  /tools                 → [{ name, description }]
+ *   GET  /health                → { status: "ok" }
+ *
+ * Writes a PID file to ~/.opera-browser-cli/bridge.pid on startup.
+ */
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import type { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
+export interface BridgeContentBlock {
+    type: string;
+    text?: string;
+}
+export interface BridgeCallPayload {
+    name: string;
+    args: Record<string, unknown>;
+}
+interface BridgeToolDescription {
+    name: string;
+    description?: string;
+}
+export interface BridgeClient {
+    listTools(): Promise<{
+        tools: BridgeToolDescription[];
+    }>;
+    callTool(request: {
+        name: string;
+        arguments: Record<string, unknown>;
+    }, resultSchema?: unknown, options?: RequestOptions): Promise<unknown>;
+    close(): Promise<void>;
+}
+export declare function isBridgeClientConnected(client: BridgeClient): Promise<boolean>;
+export declare function getErrorMessage(error: unknown): string;
+export declare function extractToolText(content: BridgeContentBlock[]): string;
+export declare function parseBridgeCallPayload(body: string): BridgeCallPayload;
+export declare function resolveBridgeScript(importMetaDir: string): string;
+export declare function handleBridgeRequest(client: BridgeClient, req: IncomingMessage, res: ServerResponse, captureNextId?: () => Promise<string>): Promise<void>;
+export declare function createBridgeServer(client: BridgeClient, captureNextId?: () => Promise<string>): Server;
+export declare function buildTransportArgs(): string[];
+/**
+ * Wraps transport.send to intercept outgoing JSON-RPC request IDs so each
+ * streaming callTool call can register its own log writer before the first
+ * notification arrives.
+ *
+ * INVARIANT: The MCP SDK's Client.request() calls transport.send() synchronously
+ * inside its Promise constructor (see @modelcontextprotocol/sdk shared/protocol.js).
+ * This means callTool() triggers transport.send before yielding, allowing us to
+ * capture the ID before any concurrent handler can interleave.
+ * Verify this invariant when upgrading @modelcontextprotocol/sdk.
+ */
+export declare function wrapTransportForIdCapture(transport: StdioClientTransport): () => Promise<string>;
+export declare function runBridge(port?: number): Promise<void>;
+export {};