opera-browser-cli 0.1.45 → 0.1.46

package/dist/src/browser-target.js

@@ -0,0 +1,161 @@
+/**
+ * Decide what browser the bridge should talk to, before it starts.
+ *
+ * The constraint that shapes all of this: --remote-debugging-port is a
+ * startup-only flag. A browser the user opened normally cannot be attached to,
+ * ever. So there is no way to "connect to the Opera that is already open" —
+ * only ways to arrange that the open Opera was started with a port in the first
+ * place, and a way to detect it when it was.
+ *
+ * That gives three states for a configured profile:
+ *
+ *   free                        → let opera-devtools-mcp launch it, as before.
+ *   locked, debug port live     → attach. No prompt, no restart, nothing to do.
+ *   locked, no debug port       → a conflict only the user can resolve, by
+ *                                 letting us restart their browser.
+ *
+ * The second case is the one that makes this feel automatic: once a browser has
+ * been started with a port — by us, or by the user following `launch-args` —
+ * every later command finds it on its own via DevToolsActivePort.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { findAttachableEndpoint, inspectProfileLock, probeDevToolsEndpoint, readDevToolsPort, } from "./profile.js";
+export async function resolveBrowserTarget(ctx) {
+    // An explicit browser URL is the user telling us they manage the browser.
+    if (ctx.browserUrl) {
+        return { mode: "attach", url: ctx.browserUrl, note: "OPERA_CLI_BROWSER_URL" };
+    }
+    // No persistent profile means an isolated one, which nothing else can hold.
+    if (!ctx.userDataDir) {
+        return { mode: "managed", note: "isolated profile" };
+    }
+    // A live debug port wins outright: the browser is running and reachable, so
+    // there is no conflict to resolve regardless of what the lock says.
+    const attachable = await findAttachableEndpoint(ctx.userDataDir);
+    if (attachable !== null) {
+        return {
+            mode: "attach",
+            url: attachable.url,
+            note: `running ${attachable.identity.browser}`,
+        };
+    }
+    const lock = inspectProfileLock(ctx.userDataDir);
+    if (lock.state === "free") {
+        return { mode: "managed", note: "profile is free" };
+    }
+    return { mode: "conflict", userDataDir: ctx.userDataDir, lock };
+}
+// ---------------------------------------------------------------------------
+// Takeover
+// ---------------------------------------------------------------------------
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * Ask a running browser to quit, and wait for it to let go of the profile.
+ *
+ * SIGTERM only. Chromium treats it as a clean shutdown — session saved, profile
+ * flushed — whereas SIGKILL risks a corrupted profile and loses the user's
+ * tabs. If it will not go, we say so rather than escalating: this is somebody's
+ * browser, and forcing it is not ours to decide.
+ */
+export async function quitBrowser(lock, userDataDir, timeoutMs = 20_000) {
+    if (lock.pid === null)
+        return { ok: false, reason: "no-pid" };
+    try {
+        process.kill(lock.pid, "SIGTERM");
+    }
+    catch {
+        // Already gone between inspection and now — that is a success.
+        return { ok: true };
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        await sleep(250);
+        if (inspectProfileLock(userDataDir).state === "free")
+            return { ok: true };
+    }
+    return { ok: false, reason: "timeout" };
+}
+/**
+ * Start a browser we can attach to, and that outlives us.
+ *
+ * `--remote-debugging-port=0` has Chromium pick a free port itself and record
+ * it in DevToolsActivePort. That satisfies two requirements at once: we never
+ * squat a predictable port like 9222, and the port is discoverable by every
+ * later command without being written to any config.
+ *
+ * The browser is detached deliberately. Having just restarted the user's
+ * browser, closing it again when the CLI's bridge stops would be a poor trade.
+ */
+export async function launchAttachableBrowser(executablePath, userDataDir, extraArgs = [], timeoutMs = 30_000) {
+    if (!executablePath || !existsSync(executablePath)) {
+        return { ok: false, reason: "no-executable" };
+    }
+    // Chromium rewrites this on startup, but clearing it first means a stale port
+    // from a previous run can never be mistaken for the new browser's.
+    const portFile = join(userDataDir, "DevToolsActivePort");
+    try {
+        unlinkSync(portFile);
+    }
+    catch {
+        // Absent already — fine.
+    }
+    const args = [
+        "--remote-debugging-port=0",
+        // Explicit even though it is the default: the debug port must never be
+        // reachable from off-box.
+        "--remote-debugging-address=127.0.0.1",
+        `--user-data-dir=${userDataDir}`,
+        // We just took their browser away; give the tabs back.
+        "--restore-last-session",
+        ...extraArgs,
+    ];
+    let child;
+    try {
+        child = spawn(executablePath, args, { stdio: "ignore", detached: true });
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: "spawn-failed",
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+    child.unref();
+    let spawnError = null;
+    child.on("error", (error) => {
+        spawnError = error.message;
+    });
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (spawnError !== null) {
+            return { ok: false, reason: "spawn-failed", detail: spawnError };
+        }
+        const port = readDevToolsPort(userDataDir);
+        if (port !== null && (await probeDevToolsEndpoint(port)) !== null) {
+            return { ok: true, url: `http://127.0.0.1:${port}` };
+        }
+        await sleep(250);
+    }
+    return { ok: false, reason: "timeout" };
+}
+/**
+ * The flags a user needs to start Opera themselves so the CLI can attach.
+ *
+ * Deliberately not `--remote-allow-origins=*`: Chromium's default rejection of
+ * CDP WebSocket upgrades that carry an Origin header is what stops a web page
+ * from driving the browser, and this profile is logged into everything.
+ */
+export function browserLaunchArgs(userDataDir) {
+    const args = [
+        "--remote-debugging-port=0",
+        "--remote-debugging-address=127.0.0.1",
+    ];
+    if (userDataDir)
+        args.push(`--user-data-dir=${userDataDir}`);
+    return args;
+}
+//# sourceMappingURL=browser-target.js.map

package/dist/src/browser-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-target.js","sourceRoot":"","sources":["../../src/browser-target.ts"],"names":[],"mappings":"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"}

package/dist/src/cli.d.ts

@@ -1,9 +1,10 @@
+import { type ErrorCode, type BridgeStatus, type StopResult } from "./client.js";
 type CliStdout = Pick<NodeJS.WriteStream, "write">;
 export type MainOptions = {
     argv?: string[];
     stdout?: CliStdout;
 };
-export declare const TOP_HELP = "usage: opera-browser-cli [command] [args] [flags]\ncommands[41]:\n  open <url>, snapshot, screenshot <path>, click @<uid>, fill @<uid> <text>,\n  type <text>, press <key>, scroll <dir>, back, wait <ms|text>, eval <js>,\n  run,\n  hover @<uid>, drag @<from> @<to>, fillform @<uid>=<val>..., dialog <action>,\n  upload @<uid> <path>, pages, newpage <url>, selectpage <id>, closepage <id>,\n  resize <w> <h>, emulate, console, console-get <id>, network,\n  network-get [id], lighthouse, perf-start, perf-stop,\n  perf-insight <set> <name>, heap <path>, start, stop,\n  chat [--model <id>] <prompt>, invoke-do <prompt>, make <prompt>,\n  research <prompt>, models,\n  setup, logs, doctor\n\nflags[2]:\n  --help, -v/-V/--version\n\nenvironment:\n  OPERA_CLI_HEADED        Set to 1 to run Chrome in headed (visible) mode\n  OPERA_CLI_CHROME_ARGS   Whitespace-separated Chrome flags forwarded to the browser\n                                    (no shell-style quoting; flags with spaces are not supported)\n                                    e.g. \"--enable-gpu --ignore-gpu-blocklist\"\n  OPERA_CLI_PORT          Bridge server port (default: 9225)\n  OPERA_CLI_BROWSER_URL   Connect to an existing Chrome instance instead of launching one\n                                    e.g. \"http://127.0.0.1:9222\"\n  OPERA_CLI_USER_DATA_DIR Persistent Chrome profile directory (skips --isolated mode)\n                                    e.g. \"/path/to/.chrome-profile\"\n  OPERA_CLI_EXECUTABLE_PATH  Path to a custom browser binary (e.g. Opera Neon)\n  OPERA_CLI_ENABLE_HOOKS  Set to 1 to auto-install session hooks on startup\n\n  Environment variables can also be set in ~/.opera-browser-cli/config (KEY=VALUE, one per line).\n  Run `opera-browser-cli setup` to configure interactively.\n\nopera ai:\n  chat is available on any Opera browser. Use --model to select a model.\n  Run \"models\" to list available models.\n  invoke-do, make, and research require Opera Neon with an active sign-in.\n  Run `opera-browser-cli setup` to configure the executable path, or set\n  OPERA_CLI_EXECUTABLE_PATH=\"/Applications/Opera Neon.app/Contents/MacOS/Opera\".\n\ngpu:\n  Headless Chrome cannot access hardware GPU on most Linux systems.\n  For GPU-accelerated WebGL, use headed mode with GPU flags:\n    OPERA_CLI_HEADED=1\n    OPERA_CLI_CHROME_ARGS=\"--enable-gpu --ignore-gpu-blocklist\"\n  For WebGPU, Vulkan must also be enabled (required for the Dawn backend):\n    OPERA_CLI_CHROME_ARGS=\"--enable-gpu --ignore-gpu-blocklist --enable-unsafe-webgpu --enable-features=Vulkan\"\n\ntips:\n  Pipe output through grep/head to extract specific data from large pages.\n";
+export declare const TOP_HELP = "usage: opera-browser-cli [command] [args] [flags]\ncommands[46]:\n  open <url>, snapshot, screenshot <path>, click @<uid>, fill @<uid> <text>,\n  type <text>, press <key>, scroll <dir>, back, wait <ms|text>, eval <js>,\n  run,\n  hover @<uid>, drag @<from> @<to>, fillform @<uid>=<val>..., dialog <action>,\n  upload @<uid> <path>, pages, newpage <url>, selectpage <id>, closepage <id>,\n  resize <w> <h>, emulate, console, console-get <id>, network,\n  network-get [id], lighthouse, perf-start, perf-stop,\n  perf-insight <set> <name>, heap <path>, start, stop, restart, status,\n  attach, launch-args, login,\n  chat [--model <id>] <prompt>, invoke-do <prompt>, make <prompt>,\n  research <prompt>, models,\n  setup, logs, doctor\n\nexit codes:\n  0 ok   2 bad arguments   3 environment not ready   4 sign-in required\n  5 timed out (retry)      6 stale page ref (re-snapshot)   1 other\n\nflags[3]:\n  --help, -v/-V/--version, --takeover\n\nenvironment:\n  OPERA_CLI_HEADED        Set to 1 to run Chrome in headed (visible) mode\n  OPERA_CLI_CHROME_ARGS   Whitespace-separated Chrome flags forwarded to the browser\n                                    (no shell-style quoting; flags with spaces are not supported)\n                                    e.g. \"--enable-gpu --ignore-gpu-blocklist\"\n  OPERA_CLI_PORT          Base bridge port (default: 9225); the next 9 ports are\n                                    tried in turn if it is occupied\n  OPERA_CLI_BROWSER_URL   Connect to an existing Chrome instance instead of launching one\n                                    e.g. \"http://127.0.0.1:9222\"\n  OPERA_CLI_USER_DATA_DIR Persistent Chrome profile directory (skips --isolated mode)\n                                    e.g. \"/path/to/.chrome-profile\"\n  OPERA_CLI_EXECUTABLE_PATH  Path to a custom browser binary (e.g. Opera Neon)\n  OPERA_CLI_ENABLE_HOOKS  Set to 1 to auto-install session hooks on startup\n  OPERA_CLI_TAKEOVER      Set to 1 to allow restarting a running Opera without\n                                    asking (same as the --takeover flag)\n\n  Environment variables can also be set in ~/.opera-browser-cli/config (KEY=VALUE, one per line).\n  Run `opera-browser-cli setup` to configure interactively.\n\nopera ai:\n  chat is available on any Opera browser. Use --model to select a model.\n  Run \"models\" to list available models.\n  invoke-do, make, and research require Opera Neon with an active sign-in.\n  Run `opera-browser-cli setup` to configure the executable path, or set\n  OPERA_CLI_EXECUTABLE_PATH=\"/Applications/Opera Neon.app/Contents/MacOS/Opera\".\n\ngpu:\n  Headless Chrome cannot access hardware GPU on most Linux systems.\n  For GPU-accelerated WebGL, use headed mode with GPU flags:\n    OPERA_CLI_HEADED=1\n    OPERA_CLI_CHROME_ARGS=\"--enable-gpu --ignore-gpu-blocklist\"\n  For WebGPU, Vulkan must also be enabled (required for the Dawn backend):\n    OPERA_CLI_CHROME_ARGS=\"--enable-gpu --ignore-gpu-blocklist --enable-unsafe-webgpu --enable-features=Vulkan\"\n\ntips:\n  Pipe output through grep/head to extract specific data from large pages.\n";
 export declare function getCommandHelp(command: string): string | null;
 export interface ScreenshotArgs {
     filePath: string | null;
@@ -61,9 +62,59 @@ export declare function parsePerfStartArgs(args: string[]): {
     autoStop?: boolean;
     filePath?: string;
 };
+/**
+ * Exit codes, so a caller can branch on *why* something failed without parsing
+ * the message. Documented in README.md and SKILL.md — treat as a contract.
+ *
+ *   2 fix the command    3 environment not ready    4 ask the user
+ *   5 retry later        6 page state moved; re-snapshot
+ */
+export declare const EXIT_CODES: Record<ErrorCode, number>;
+export declare function exitCodeForCdpError(error: unknown): number;
+export declare function formatCliError(error: unknown): {
+    output: string;
+    exitCode: number;
+};
 /** Wrap plain JS expressions for MCP evaluate_script, but pass functions through unchanged. */
 export declare function wrapJsExpression(js: string): string;
-export declare function formatStopOutput(wasStopped: boolean): string;
+export declare function formatStopOutput(result: StopResult): string;
+export declare function formatStatusOutput(status: BridgeStatus): string;
+export interface SetupArgs {
+    interactive: boolean;
+    executable: string | undefined;
+    profile: string | undefined;
+    headed: boolean | undefined;
+}
+export declare function parseSetupArgs(args: string[]): SetupArgs;
+export declare function parseAttachArgs(args: string[]): {
+    port: number | null;
+    clear: boolean;
+};
+export declare function parseLogsArgs(args: string[]): {
+    lines: number;
+    follow: boolean;
+    errorsOnly: boolean;
+};
+export declare function filterLogLines(lines: string[], errorsOnly: boolean): string[];
+/**
+ * Pre-flight check for AI commands. Fails fast if Opera Neon is clearly
+ * not configured, so we don't pay the 30s bridge-startup tax just to surface
+ * a confusing protocol error.
+ *
+ * Skipped when OPERA_CLI_BROWSER_URL is set — the user manages the browser
+ * themselves and presumably knows it's Opera Neon.
+ */
+export type BrowserKind = "neon" | "opera" | "other" | "unknown";
+/**
+ * What kind of browser we are about to drive.
+ *
+ * The old check only asked whether the configured path existed, which cannot
+ * tell Neon from Opera from Chrome — so it passed in exactly the two cases that
+ * fail: a plain Opera (no invoke-do/make/research) and a non-Opera browser
+ * (no Opera AI at all). Attached browsers report their real identity; launched
+ * ones are identified by their build, which is how Opera names its binaries.
+ */
+export declare function classifyBrowser(executablePath: string | undefined, attachedBrowser?: string | undefined): BrowserKind;
 declare const VALID_RESEARCH_TYPES: readonly ["local", "one-minute", "deep"];
 type ResearchType = (typeof VALID_RESEARCH_TYPES)[number];
 export declare function parseChatArgs(args: string[]): {
@@ -74,5 +125,24 @@ export declare function parseResearchArgs(args: string[]): {
     prompt: string;
     researchType?: ResearchType;
 };
+/**
+ * Work out which browser this command should drive, before the bridge starts.
+ *
+ * Runs in the CLI rather than the bridge because resolving a conflict may need
+ * to ask the user something, and the bridge is detached with no terminal.
+ *
+ * This runs even when a bridge is already alive. A bridge fixes its browser
+ * (attach URL, profile, flags) at startup, so a healthy bridge is only "the
+ * question is settled" while it is still driving the right browser. The case
+ * that must never be silently skipped is a conflict: the user's own Opera is
+ * running on the configured profile without a debug port. That used to be
+ * bypassed whenever any bridge was running, so the restart prompt never fired
+ * and the CLI kept driving a stale headless / separate-profile browser.
+ */
+export declare function preflightBrowser(argv: string[], takeover: boolean): Promise<void>;
+export declare function extractTakeoverFlag(argv: string[]): {
+    argv: string[];
+    takeover: boolean;
+};
 export declare function main(options?: MainOptions | string[]): Promise<void>;
 export {};