opera-browser-cli 0.1.45 → 0.1.46

package/README.md

@@ -13,10 +13,13 @@ It wraps [opera-devtools-mcp](https://github.com/operasoftware/opera-devtools-mc
 
 ```sh
 npm install -g opera-browser-cli
-opera-browser-cli setup   # interactive wizard — run in a terminal where you can answer prompts
 opera-browser-cli open https://example.com
 ```
 
+That is the whole setup. The first command detects your Opera installation,
+writes `~/.opera-browser-cli/config`, and gets on with it. Run
+`opera-browser-cli setup` only when you want to change what it chose.
+
 Once installed, `open` navigates to a URL and returns a structured snapshot you can act on:
 
 ```sh
@@ -64,21 +67,30 @@ Prerequisites: **Node.js >= 20**, **Opera** browser ([Opera Neon](https://www.op
 npm install -g opera-browser-cli
 ```
 
-Run first-time setup — this is an interactive wizard, so run it in a terminal where you can answer prompts:
+No setup step is required. The first command you run detects your Opera
+installation, writes `~/.opera-browser-cli/config`, and continues:
 
 ```sh
-opera-browser-cli setup
+opera-browser-cli --version
+opera-browser-cli open https://example.com
 ```
 
-This detects Opera installations, lets you pick one, saves configuration to `~/.opera-browser-cli/config`, and installs the skill to `~/.claude/skills/opera-browser-cli/SKILL.md` (Claude Code) and `~/.agents/skills/opera-browser-cli/SKILL.md` (generic cross-agent path used by Codex and other agents).
-
-Verify:
+`setup` exists for when you want to change that choice — pick a different
+browser or profile, or install the agent skill files:
 
 ```sh
-opera-browser-cli --version
-opera-browser-cli open https://example.com
+opera-browser-cli setup             # interactive wizard
+opera-browser-cli setup -y          # detect and accept, no prompts
+opera-browser-cli setup --executable "/Applications/Opera Neon.app/Contents/MacOS/Opera" \
+                        --profile skip --headless
 ```
 
+It saves to `~/.opera-browser-cli/config` and installs the skill to
+`~/.claude/skills/opera-browser-cli/SKILL.md` (Claude Code) and
+`~/.agents/skills/opera-browser-cli/SKILL.md` (generic cross-agent path used by
+Codex and other agents). The non-interactive form needs no terminal, so agents
+and provisioning scripts can run it too.
+
 ### From source
 
 ```sh
@@ -86,7 +98,7 @@ opera-browser-cli open https://example.com
 npm install && npm run build && npm link
 ```
 
-Then run `opera-browser-cli setup` as above.
+Then just run a command — configuration happens on first use.
 
 ### Usage examples
 
@@ -127,7 +139,7 @@ OPERA_CLI_BROWSER_URL=http://127.0.0.1:9222 opera-browser-cli open https://examp
 ```
 
 - **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`
+- **Auto-lifecycle** — the bridge starts on first command, writes a PID file to `~/.opera-browser-cli/bridge.pid`, and restarts itself on version skew or a dropped connection
 - **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
 
@@ -219,14 +231,83 @@ opera-browser-cli eval "(() => { const rows = [...document.querySelectorAll('tr'
 |----------|--------------------------------------------------|
 | `setup`  | Interactive first-time setup (browser path, etc) |
 | `doctor` | Check configuration and environment              |
+| `doctor --fix` | Repair what can be repaired mechanically   |
+| `login` | Sign in to your Opera account (needed for AI)    |
 | `logs`   | Show bridge server logs                          |
 
+### Using your real Opera profile
+
+By default the CLI launches its own browser. To drive **your** Opera — with your
+logins, your session — the browser has to have been started with a debugging
+port. That flag cannot be added to a browser that is already open, so there are
+two ways in:
+
+```sh
+opera-browser-cli launch-args   # prints the command to start Opera with a port
+```
+
+Start Opera that way once, and every later command finds it automatically — the
+port is recorded in `DevToolsActivePort` inside the profile, so nothing needs
+configuring. Or let the CLI do it for you:
+
+```sh
+opera-browser-cli open example.com    # detects the conflict, offers to restart Opera
+opera-browser-cli open example.com --takeover   # skip the prompt (scripts, agents)
+```
+
+If Opera is already running on the configured profile and has no debugging port,
+the CLI asks whether to restart it (tabs are restored). Without a terminal to ask
+in, it quietly uses a separate profile instead — an agent will never quit your
+browser on its own. Restarting is always SIGTERM, never SIGKILL: a forced kill
+risks a corrupted profile.
+
+```sh
+opera-browser-cli attach --port 9222   # connect to a specific endpoint
+opera-browser-cli attach --clear       # go back to a CLI-launched browser
+```
+
+> **Note:** a debugging port has no authentication of its own — the CLI's bearer
+> token protects the bridge, not the browser. Any local process can drive a
+> browser with an open port, and this one is signed into everything you are. The
+> CLI lets the browser pick a random port rather than a predictable 9222, binds
+> it to loopback, and never passes `--remote-allow-origins`, which is what stops
+> a web page from driving it. Close the browser when you are done.
+
 ### Bridge
 
-| Command | Description             |
-|---------|-------------------------|
-| `start` | Start the bridge server |
-| `stop`  | Stop the bridge server  |
+| Command   | Description                                                        |
+|-----------|--------------------------------------------------------------------|
+| `start`   | Start the bridge server                                            |
+| `stop`    | Stop the bridge server (escalates to SIGKILL; clears a stale PID)  |
+| `restart` | Stop and start again — forces a clean state                        |
+| `status`  | Report bridge pid, port, and running version without starting one  |
+
+You should rarely need any of these. The bridge starts on first use, and repairs
+itself without being asked:
+
+- **Upgraded package** — a bridge running pre-upgrade code is detected by version
+  and replaced on the next command.
+- **Crashed or killed bridge** — the next command restarts it and retries. Opera AI
+  commands are the exception: they are never silently re-run, since they may already
+  have acted on the page.
+- **Port in use** — the next port in the range is used instead of failing.
+- **Several commands at once** — a start lock means exactly one bridge comes up.
+- **Stale PID file** — cleared automatically, and never signalled if the PID could
+  belong to an unrelated process from before a reboot.
+
+### Exit codes
+
+Scripts and agents can branch on why a command failed without parsing messages:
+
+| Code | Meaning | Caller action |
+|---|---|---|
+| 0 | Success | — |
+| 1 | Unknown / internal | Report |
+| 2 | Bad arguments, or unsupported on this browser | Fix the command |
+| 3 | Environment not ready after auto-recovery | Run `doctor` |
+| 4 | Sign-in, subscription, or consent required | Ask the user |
+| 5 | Timed out | Retry |
+| 6 | Stale element ref or closed page | Re-snapshot, then retry |
 
 Running with no command shows the CLI home view. It prepends `bin` and
 `description` metadata, then includes the current snapshot when a browser
@@ -265,14 +346,15 @@ session is active or the no-session status/help block when one is not.
 
 | Variable                    | Default                          | Purpose                                                          |
 |-----------------------------|----------------------------------|------------------------------------------------------------------|
-| `OPERA_CLI_PORT`            | `9225`                           | Bridge server port                                               |
+| `OPERA_CLI_PORT`            | `9225`                           | Base bridge port; the next 9 are tried if it is occupied         |
 | `OPERA_CLI_MCP_BIN`         | _(bundled `opera-devtools-mcp`)_ | Override the 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_HEADED`          | `1` when an Opera binary is configured | `1` headed, `0` headless. Opera AI needs a window to sign in |
 | `OPERA_CLI_CHROME_ARGS`     | —                                | Extra Chrome flags, space-separated                              |
 | `OPERA_CLI_ENABLE_HOOKS`    | —                                | Set to `1` to auto-install session hooks on startup              |
+| `OPERA_CLI_TAKEOVER`        | —                                | Set to `1` to restart a running Opera without asking             |
 
 State is stored in `~/.opera-browser-cli/`:
 

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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 AI features (chat available on any Opera browser; invoke-do, make, research require Opera Neon).
+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 AI features (chat available on any Opera browser; invoke-do, make, research require Opera Neon). When a browser is already running without automation enabled, this tool can restart it with a debug port (takeover) or use a separate profile — ask the user which they prefer.
 metadata: {"openclaw": {"requires": {"bins": ["opera-browser-cli"]}}}
 ---
 
@@ -47,6 +47,35 @@ Commands that accept these flags: `open`, `snapshot`, `click`, `fill`, `type`, `
 
 To wire this CLI into a Docker-based OpenClaw setup (Chromium sidecar, shared netns, config bootstrap), see [`openclaw/README.md`](openclaw/README.md).
 
+## Exit codes
+
+Branch on the exit code rather than parsing messages:
+
+| Code | Meaning | What to do |
+|---|---|---|
+| 0 | Success | — |
+| 2 | Bad arguments, or the browser cannot do this | Fix the command; do not retry as-is |
+| 3 | Environment not ready after auto-recovery | Run `opera-browser-cli doctor` |
+| 4 | Sign-in, subscription, or consent needed | Ask the user — you cannot fix this |
+| 5 | Timed out | Retry |
+| 6 | Stale element ref or closed page | Re-run `snapshot`, then retry with fresh refs |
+| 1 | Anything else | Report it |
+
+## Recovery is automatic
+
+The bridge restarts itself on version skew, a crash, or a dropped connection, and falls back to another port if one is taken. Do not run `stop`/`restart` speculatively — just re-run the command. The exception is the Opera AI tools (`invoke-do`, `make`, `research`, `chat`): if one reports the connection dropped mid-call, it was **not** retried, because it may already have acted. Ask before re-running it.
+
+## When the browser can't be automated
+
+The CLI only drives a browser started with a debug port. If the user's Opera is already open **without** one, the CLI can't attach to that window — `open`/AI then fail with **"Could not connect to Chrome"**. Run `opera-browser-cli doctor` (it reports the profile state); the bridge self-heals, so don't restart it blindly.
+
+**Always ask the user** — restarting their browser is their call, not a judgement you infer:
+> "Your Opera is open but wasn't started with automation. May I restart it with a debug port (tabs restored)? Or should I use a separate profile (you'd sign in there)?"
+
+- **They approve restart** → run with `--takeover` (or `OPERA_CLI_TAKEOVER=1`). Restarts with a debug port, restores tabs, attaches — drives the real browser thereafter.
+- **They decline** → no flag → separate profile at `~/.opera-browser-cli/profile` (they sign in there; AI may then return exit `4` — surface it).
+- `opera-browser-cli launch-args` prints the flags to start Opera attachable so a restart is never needed later.
+
 ## Sign-in errors
 
-If you hit `Opera: user is not signed in` on an AI command, suggest signing in to their Opera account. Run `opera-browser-cli setup` or `opera-browser-cli doctor` to configure or diagnose.
+If an AI command fails with `AUTH_REQUIRED` (exit code 4) — not signed in, no subscription, or consent pending — tell the user to run `opera-browser-cli login`, which opens the Opera account page in a visible window. `opera-browser-cli login --check` verifies the current state. Run `opera-browser-cli doctor` to diagnose anything else.

package/dist/src/bridge.d.ts

@@ -13,6 +13,7 @@
 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";
+import { type BridgeHealth } from "./identity.js";
 export interface LastSnapshotCache {
     raw: string;
     pageUrl: string | null;
@@ -44,10 +45,38 @@ export interface BridgeClient {
     close(): Promise<void>;
 }
 export declare function isBridgeClientConnected(client: BridgeClient): Promise<boolean>;
+/**
+ * "Usable" health for the bridge: the MCP server is up AND, when the bridge is
+ * in attach mode, the browser at the attach URL is actually reachable.
+ *
+ * In attach mode devtools-mcp stays connected over stdio even when the browser
+ * it points at is gone (it reaches for the browser lazily on a tool call), so
+ * MCP liveness alone cannot tell that a bridge is wedged on a dead URL. Probing
+ * the attach endpoint directly keeps `/health` honest, which lets the CLI stop
+ * reusing a wedged bridge and rebuild it against the current target.
+ */
+export declare function isBridgeHealthConnected(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 type BridgeLauncher = {
+    ok: true;
+    command: string;
+    args: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Decide how to launch the bridge process.
+ *
+ * Prefers the built JavaScript. The TypeScript entrypoint is used only in a
+ * source checkout (or under OPERA_CLI_DEV=1), and only when tsx is already
+ * installed — never via `npx`, which blocks on an install prompt when the
+ * package is uncached and would hang invisibly behind a redirected stdio.
+ */
+export declare function resolveBridgeLauncher(importMetaDir: string, execPath?: string): BridgeLauncher;
 /** True when a Host/Origin host component (with optional port) is loopback. */
 export declare function isLoopbackHost(hostHeader: string | undefined): boolean;
 /** Browsers always attach Origin; the CLI never does. Absent = trusted; present = must be loopback. */
@@ -65,9 +94,48 @@ export interface BridgeAccessResult {
  */
 export declare function checkRequestAccess(req: IncomingMessage, token: string | null, requireToken: boolean): BridgeAccessResult;
 export declare function generateBridgeToken(): string;
+export declare function buildHealth(connected: boolean): BridgeHealth;
 export declare function handleBridgeRequest(client: BridgeClient, req: IncomingMessage, res: ServerResponse, captureNextId?: () => Promise<string>, token?: string | null): Promise<void>;
-export declare function createBridgeServer(client: BridgeClient, captureNextId?: () => Promise<string>, token?: string | null): Server;
+/**
+ * Build the HTTP server.
+ *
+ * `resolve` is called per request rather than the client being captured up
+ * front, so the port can be bound before the MCP connection exists. Until it
+ * returns a client every route answers 503 with a well-formed health body —
+ * which is exactly what a caller probing /health during startup should see.
+ */
+export declare function createBridgeServer(resolve: () => {
+    client: BridgeClient | null;
+    captureNextId?: () => Promise<string>;
+}, token?: string | null): Server;
+/** Exit code signalling "port taken, try the next one" (EX_TEMPFAIL). */
+export declare const EXIT_PORT_IN_USE = 75;
+/**
+ * Whether to launch a visible browser.
+ *
+ * Headless is the safe default for a tool — it is the only thing that works on
+ * a server with no display. But a configured Opera binary means the user wants
+ * *their* browser, and every Opera AI feature needs a window: sign-in and
+ * consent cannot be completed headlessly, so a headless AI command fails on a
+ * state the user has no way to fix.
+ *
+ * So: headed when an Opera executable is configured, headless otherwise, and
+ * OPERA_CLI_HEADED=0 or =1 overrides either way. A machine with no Opera
+ * installed — CI, Docker, a plain-Chrome setup — keeps the old behaviour.
+ */
+export declare function shouldRunHeaded(): boolean;
 export declare function buildTransportArgs(): string[];
+export interface McpBinStatus {
+    bin: string;
+    found: boolean;
+    source: "env" | "dependency" | "path";
+}
+/**
+ * Where opera-devtools-mcp is coming from, and whether it is actually there.
+ * Used by `doctor` so a missing MCP server is named before it costs a failed
+ * bridge start.
+ */
+export declare function resolveMcpBinStatus(): McpBinStatus;
 /**
  * Wraps transport.send to intercept outgoing JSON-RPC request IDs so each
  * streaming callTool call can register its own log writer before the first