opera-devtools-mcp 0.7.0 → 0.8.0

package/build/src/opera/logs.js

@@ -0,0 +1,133 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * `logs` — tail the daemon's log, optionally following it or filtering to the
+ * lines that matter.
+ *
+ * Ported from opera-browser-cli's `src/cli.ts`. The file is the daemon's own
+ * stdout/stderr (`opera/daemonLog.ts`), so everything the source read from the
+ * bridge log is here: no extra state, and one less process to keep alive.
+ *
+ * Rotation is the daemon's, done on startup, so unlike the source there is no
+ * rotation command — `followLog` still handles a shrinking file, because
+ * `doctor --fix` can rotate under a running tail.
+ */
+import { closeSync, existsSync, openSync, readFileSync, readSync, statSync, } from 'node:fs';
+import { CLI_BIN_NAME } from './branding.js';
+import { encode, renderHelp, renderOutput } from './cliOutput.js';
+import { getDaemonLogPath } from './daemonLog.js';
+const LOGS_DEFAULT_LINES = 50;
+export function parseLogsArgs(args) {
+    let lines = LOGS_DEFAULT_LINES;
+    let follow = false;
+    let errorsOnly = false;
+    for (let i = 0; i < args.length; i++) {
+        if ((args[i] === '-n' || args[i] === '--lines') && i + 1 < args.length) {
+            const parsed = Number.parseInt(args[++i] ?? '', 10);
+            if (Number.isFinite(parsed) && parsed > 0) {
+                lines = parsed;
+            }
+        }
+        else if (args[i] === '-f' || args[i] === '--follow') {
+            follow = true;
+        }
+        else if (args[i] === '--errors') {
+            errorsOnly = true;
+        }
+    }
+    return { lines, follow, errorsOnly };
+}
+/** The lines worth looking at when something has gone wrong. */
+const LOG_ERROR_PATTERN = /error|failed|fatal|exception|refused|denied|timeout|timed out|in use|EADDRINUSE|ECONNREFUSED|EACCES|not found|unauthorized|cannot/i;
+export function filterLogLines(lines, errorsOnly) {
+    return errorsOnly
+        ? lines.filter(line => LOG_ERROR_PATTERN.test(line))
+        : lines;
+}
+/** Stream appended log output until interrupted. */
+async function followLog(logFile, errorsOnly) {
+    let offset = existsSync(logFile) ? statSync(logFile).size : 0;
+    let stop = false;
+    const onSigint = () => {
+        stop = true;
+    };
+    process.on('SIGINT', onSigint);
+    try {
+        while (!stop) {
+            await new Promise(resolve => setTimeout(resolve, 500));
+            if (!existsSync(logFile)) {
+                continue;
+            }
+            const size = statSync(logFile).size;
+            // A rotation shrinks the file; start over from the top of the new one.
+            if (size < offset) {
+                offset = 0;
+            }
+            if (size === offset) {
+                continue;
+            }
+            const fd = openSync(logFile, 'r');
+            try {
+                const buffer = Buffer.alloc(size - offset);
+                readSync(fd, buffer, 0, buffer.length, offset);
+                offset = size;
+                const fresh = filterLogLines(buffer.toString('utf-8').split('\n').filter(Boolean), errorsOnly);
+                if (fresh.length > 0) {
+                    process.stdout.write(fresh.join('\n') + '\n');
+                }
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+    }
+    finally {
+        process.off('SIGINT', onSigint);
+    }
+}
+export async function handleLogs(args, sessionId) {
+    const { lines, follow, errorsOnly } = parseLogsArgs(args);
+    const logFile = getDaemonLogPath(sessionId);
+    if (!existsSync(logFile)) {
+        return renderOutput([
+            await encode({ logs: 'no log file yet', path: logFile }),
+            renderHelp([
+                `Run any command (e.g. \`${CLI_BIN_NAME} start\`) to start the daemon`,
+            ]),
+        ]);
+    }
+    const allLines = readFileSync(logFile, 'utf-8').split('\n');
+    // Drop the trailing empty line from the final newline.
+    if (allLines.length > 0 && allLines[allLines.length - 1] === '') {
+        allLines.pop();
+    }
+    const matched = filterLogLines(allLines, errorsOnly);
+    const tail = matched.slice(-lines);
+    if (follow) {
+        process.stdout.write(renderOutput([
+            await encode({ path: logFile, following: true, errors_only: errorsOnly }),
+            tail.join('\n'),
+        ]) + '\n');
+        await followLog(logFile, errorsOnly);
+        return '';
+    }
+    return renderOutput([
+        await encode({
+            path: logFile,
+            lines: tail.length,
+            total: allLines.length,
+            ...(errorsOnly ? { matched: matched.length } : {}),
+        }),
+        tail.join('\n'),
+        renderHelp([
+            `Run \`${CLI_BIN_NAME} logs --lines <N>\` to show more (default ${LOGS_DEFAULT_LINES})`,
+            `Run \`${CLI_BIN_NAME} logs --errors\` to show only failure lines`,
+            `Run \`${CLI_BIN_NAME} logs --follow\` to stream new output`,
+        ]),
+    ]);
+}
+//# sourceMappingURL=logs.js.map

package/build/src/opera/mcpServerSupervisor.js

@@ -0,0 +1,128 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * Keeps the daemon's MCP server alive.
+ *
+ * The MCP server is a stdio child of the daemon, and the SDK's transport already
+ * reports its exit through `onclose` — upstream simply never sets that callback.
+ * The daemon therefore outlives its only means of serving tools: it keeps
+ * answering `status` while every tool call fails, and the CLI has no way to tell
+ * that the session is useless.
+ *
+ * Two things make the callback harder than it looks. The close that the respawn
+ * itself causes — releasing the dead server — lands in the same callback as a
+ * real failure, so the transport object identifies itself and its own retirement
+ * is ignored. And a replacement can die while `connect()` is still running,
+ * before it is anybody's idea of "the current server": that close arrives while
+ * the respawn is in flight and is recorded, so the attempt is not mistaken for a
+ * healthy one.
+ *
+ * `giveUp` exists for the same reason in the other direction: a daemon that
+ * cannot be brought back to health must not keep answering. It records why,
+ * tears itself down, and leaves a working daemon to be started in its place
+ * instead of a zombie that reports itself ready.
+ */
+import { setTimeout as sleep } from 'node:timers/promises';
+import { logger } from '../utils/logger.js';
+import { writeExitReason } from './daemonLifecycle.js';
+const RESPAWN_ATTEMPTS = 3;
+const RESPAWN_DELAY_MS = 500;
+export function superviseMcpServer(options) {
+    let stopped = false;
+    let respawning = false;
+    /** A close that arrived while a respawn was already in flight. */
+    let respawnRequested = false;
+    /** The transport this supervisor closed itself, whose close is not a failure. */
+    let retired = null;
+    /**
+     * Let go of the server that just died, and remember it, so the close this
+     * causes is not read back as a second failure.
+     */
+    async function releaseHandles() {
+        const { client, transport } = options.handles();
+        if (transport) {
+            retired = transport;
+        }
+        try {
+            await client?.close();
+        }
+        catch (error) {
+            logger?.('Error closing MCP client:', error);
+        }
+        try {
+            // The client closes the transport too. The transport is still closed on
+            // its own because it is the thing that must not outlive the respawn, and
+            // a client that failed between construction and `connect` left it loose.
+            await transport?.close();
+        }
+        catch (error) {
+            logger?.('Error closing MCP transport:', error);
+        }
+    }
+    async function respawn() {
+        // `stop()` comes from the daemon's own teardown, which closes the client and
+        // therefore the transport and therefore lands here: a teardown must not
+        // spawn a replacement. `respawning` keeps a burst of closes to one attempt,
+        // remembering that another one arrived.
+        if (stopped) {
+            return;
+        }
+        if (respawning) {
+            respawnRequested = true;
+            return;
+        }
+        respawning = true;
+        try {
+            let lastError;
+            for (let attempt = 1; attempt <= RESPAWN_ATTEMPTS; attempt++) {
+                await releaseHandles();
+                // Any close from here on belongs to the server we are about to spawn,
+                // not to the one just released.
+                respawnRequested = false;
+                try {
+                    await options.connect();
+                    // A server that died while `connect` was still running reported itself
+                    // through `onclose`, which set the flag while it was already in flight.
+                    // `connect` resolving then proves nothing: retry rather than sit here
+                    // believing a dead server is up.
+                    if (!respawnRequested) {
+                        return;
+                    }
+                    lastError = new Error('the MCP server died during startup');
+                }
+                catch (error) {
+                    lastError = error;
+                }
+                if (attempt < RESPAWN_ATTEMPTS) {
+                    await sleep(RESPAWN_DELAY_MS);
+                }
+            }
+            throw lastError;
+        }
+        catch (err) {
+            const reason = `MCP server respawn failed after ${RESPAWN_ATTEMPTS} attempts: ${err instanceof Error ? err.message : String(err)}`;
+            logger?.(reason);
+            writeExitReason(options.sessionId, reason);
+            await options.giveUp();
+        }
+        finally {
+            respawning = false;
+        }
+    }
+    return {
+        onTransportClosed: transport => {
+            if (transport === retired) {
+                return;
+            }
+            void respawn();
+        },
+        stop: () => {
+            stopped = true;
+        },
+    };
+}
+//# sourceMappingURL=mcpServerSupervisor.js.map

package/build/src/opera/migrationShared.js

@@ -0,0 +1,164 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * Plumbing shared by the one-time two-package migration.
+ *
+ * `opera-browser-cli` used to ship as its own npm package; it now ships as a
+ * second bin inside `opera-devtools-mcp`, reached through a launcher published
+ * under the old name. The runtime migration guard (`legacyBridgeCleanup`) and
+ * the notices it prints (`launcherNotice`) need the same four facts:
+ *
+ *   1. Whether the migration is still worth running at all — the guard must not
+ *      outlive its reason for existing (see `MIGRATION_ACTIVE_UNTIL`).
+ *   2. Which home directory to look in. The old bridge is rarely started under
+ *      `sudo`, but the machine may be, and `os.homedir()` then answers for root
+ *      (`/var/root`, `/root`) while the invoking user's
+ *      `~/.opera-browser-cli/bridge.pid` is never found.
+ *   3. Where a global install put the old package — without assuming npm, whose
+ *      `npm_config_prefix` is not set by pnpm, yarn or bun.
+ *   4. How to say something. The guard must never print to stdout, which carries
+ *      the CLI's machine-readable result and the MCP server's transport.
+ */
+import { execFileSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { PACKAGE_NAME } from './branding.js';
+/**
+ * The last day the migration guard does its work. Past it the guard returns
+ * immediately, so a cleanup written for one transition cannot keep probing port
+ * windows — or keep printing its notices — forever.
+ */
+export const MIGRATION_ACTIVE_UNTIL = new Date('2027-03-01T00:00:00Z');
+/** Whether the migration guard should still do its work. */
+export function isMigrationActive(now = new Date()) {
+    return now.getTime() <= MIGRATION_ACTIVE_UNTIL.getTime();
+}
+/** Say something to the user without touching the CLI's stdout. */
+export function warn(message) {
+    process.stderr.write(`${message}\n`);
+}
+/** How long a SIGTERMed process gets before the kill escalates. */
+const STOP_GRACE_MS = 5_000;
+const STOP_POLL_MS = 100;
+/** `process.kill(pid, 0)`, treating `EPERM` (another user's live process) as alive. */
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * SIGTERM, wait, then SIGKILL — and true once the process is gone.
+ *
+ * `group: true` escalates to the whole process group, which is what a session
+ * leader's teardown needs: the daemon and the legacy bridge are both spawned
+ * `detached: true`, so the browser and the MCP server they spawned share their
+ * group and survive a signal aimed at the leader alone. Windows has no process
+ * groups, so the pid is all there is to signal.
+ */
+export async function terminateProcess(pid, options = {}) {
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch {
+        // `ESRCH` is the process we meant to stop being gone already. Anything else
+        // — `EPERM` on a process owned by another user, the common case for a
+        // bridge started with `sudo` — means the signal was not delivered, and
+        // reporting success there would hide a bridge that is still running and let
+        // its caller drop the PID file that records it.
+        return !isProcessAlive(pid);
+    }
+    const deadline = Date.now() + STOP_GRACE_MS;
+    while (Date.now() < deadline) {
+        if (!isProcessAlive(pid)) {
+            return true;
+        }
+        await sleep(STOP_POLL_MS);
+    }
+    try {
+        if (options.group && process.platform !== 'win32') {
+            process.kill(-pid, 'SIGKILL');
+        }
+        else {
+            process.kill(pid, 'SIGKILL');
+        }
+    }
+    catch {
+        return !isProcessAlive(pid);
+    }
+    await sleep(200);
+    return !isProcessAlive(pid);
+}
+/**
+ * The home directory of the user who invoked the install.
+ *
+ * Under `sudo`, that is not `os.homedir()`: `SUDO_USER`/`SUDO_UID` name the
+ * real user, and their home is what holds the legacy bridge's PID file. The
+ * lookup goes through the login shell because `~user` expansion is the only
+ * portable way to ask (Node exposes no uid→home call), and the username is
+ * validated first so it cannot smuggle shell syntax into the command.
+ *
+ * Windows is skipped: it has no `sudo`, and the `sh` that happens to be on PATH
+ * (Git Bash) answers `~user` with a POSIX path like `/c/Users/someone` — not the
+ * `os.homedir()` every other caller of this function builds its paths with.
+ */
+export function getEffectiveHome() {
+    const user = process.env.SUDO_USER;
+    if (process.platform !== 'win32' &&
+        user &&
+        process.env.SUDO_UID &&
+        /^[A-Za-z0-9._-]+$/.test(user)) {
+        try {
+            const home = execFileSync('sh', ['-c', `echo ~${user}`], {
+                encoding: 'utf8',
+                timeout: 5_000,
+            }).trim();
+            if (home.startsWith('/')) {
+                return home;
+            }
+        }
+        catch {
+            // Fall through to the process's own home.
+        }
+    }
+    return os.homedir();
+}
+/**
+ * The global install prefix, or null when it cannot be determined.
+ *
+ * Two sources, neither of which spawns a process: the environment npm and pnpm
+ * set during a global install, and this file's own location —
+ * `<prefix>/lib/node_modules/<pkg>/build/src/opera`. Asking npm was the old
+ * fallback, but this runs on every start now, and a second npm costs ~1s of
+ * process start and contends on the arborist lock npm 7+ holds during a global
+ * install. A development checkout, whose path is not inside a global
+ * `node_modules` tree, correctly reports nothing.
+ */
+export function resolveGlobalPrefix() {
+    const fromEnv = process.env.npm_config_prefix ?? process.env.NPM_CONFIG_PREFIX ?? '';
+    if (fromEnv) {
+        return fromEnv;
+    }
+    // Symlinks are resolved by default, so a pnpm/bun-linked install reports the
+    // store path and this finds no `lib/node_modules` — no prefix, no notice.
+    const parts = path.resolve(import.meta.dirname).split(path.sep);
+    const packageDir = parts.lastIndexOf(PACKAGE_NAME);
+    if (packageDir < 2 || parts[packageDir - 1] !== 'node_modules') {
+        return null;
+    }
+    const prefix = parts.slice(0, packageDir - 1);
+    if (prefix[prefix.length - 1] === 'lib') {
+        prefix.pop();
+    }
+    return prefix.join(path.sep) || path.sep;
+}
+//# sourceMappingURL=migrationShared.js.map

package/build/src/opera/operaPages.js

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * Opera's own pages, as far as the URL policy is concerned.
+ *
+ * Upstream lets Chrome's start pages through — `chrome://newtab` and
+ * `chrome://new-tab-page` — because the page a browser opens by itself is often
+ * the only page there is, and refusing it would leave `list_pages` reporting an
+ * empty browser. Opera's equivalent is the Speed Dial, and it is not a corner
+ * case: `chrome://startpageshared/` is the URL of *every* tab a user opens from
+ * the tab strip, before that tab navigates anywhere.
+ *
+ * Rejecting it costs more than a missing line of output, because the same
+ * predicate is also the Puppeteer target filter (`makeTargetFilter`). A target
+ * the filter refuses is detached at attach time and recorded as ignored
+ * (`TargetManager`), and `TargetManager` skips a target that is ignored on
+ * every later `Target.targetInfoChanged` — so the tab is never attached, never
+ * tracked, and stays invisible to `list_pages` for the rest of its life, even
+ * after the user navigates it to a real site.
+ *
+ * Upstream's own file keeps its shape; this is the one rule that decides which
+ * Opera URLs it must additionally accept.
+ */
+/**
+ * Speed Dial paths under `chrome://`. `startpageshared` is the one Opera 100+
+ * loads (and the one Opera records for its tabs); `startpage` is the older
+ * spelling, kept so a build that still uses it is not filtered.
+ */
+const OPERA_START_PAGE_PATHS = {
+    startpage: true,
+    startpageshared: true,
+};
+/**
+ * Whether the URL is one of Opera's Speed Dial pages.
+ *
+ * Accepts both the `chrome://startpageshared/` and the single-slash
+ * `chrome:startpageshared` spelling: `new URL` parses the latter with an empty
+ * host, which is how upstream's `newtab` allowance is written too.
+ */
+export function isOperaStartPage(url) {
+    if (url.protocol !== 'chrome:') {
+        return false;
+    }
+    const host = url.hostname.toLowerCase();
+    if (OPERA_START_PAGE_PATHS[host] === true) {
+        return true;
+    }
+    return (host === '' &&
+        OPERA_START_PAGE_PATHS[url.pathname.toLowerCase().split('/')[0] ?? ''] ===
+            true);
+}
+//# sourceMappingURL=operaPages.js.map

package/build/src/opera/pageIdRouting.js

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * The routing `pageId` positional is the one upstream injects into page-scoped
+ * commands; its description always opens with this sentence. Upstream appends a
+ * caveat for `evaluate_script` ("Required when not evaluating in a service
+ * worker."), so match the prefix rather than the whole string. The two commands
+ * with a `pageId` of their own (`select_page`, `close_page`) describe it in
+ * their own words and are left alone.
+ *
+ * Upstream owns this string, so `tests/opera/pageIdRouting.test.ts` pins it
+ * against the generated command table: if an intake merge rewords it, that test
+ * fails instead of the CLI silently regaining a pageId positional. The durable
+ * fix is an explicit marker on the upstream `ArgDef`.
+ */
+const ROUTING_PAGE_ID_DESCRIPTION = 'Targets a specific page by ID.';
+/**
+ * Drop the routing-injected `pageId` positional from a command's arg map. The
+ * CLI never routes by pageId, and the daemon it spawns runs with
+ * `--no-page-id-routing`, so a pageId left on the CLI surface is not merely
+ * useless — the daemon rejects it as an unknown argument.
+ */
+export function withoutRoutingPageId(args) {
+    if (args.pageId?.description.startsWith(ROUTING_PAGE_ID_DESCRIPTION)) {
+        // `_pageId` is the discarded key; the eslint config ignores `^_` vars.
+        const { pageId: _pageId, ...rest } = args;
+        return rest;
+    }
+    return args;
+}
+//# sourceMappingURL=pageIdRouting.js.map

package/build/src/opera/pageRecovery.js

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * The in-flight recovery, per context. Scoped to the context because that is all
+ * the sharing there is: Opera tools bypass the tool mutex, so two of them
+ * resolving a page at the same moment share one new page rather than open one
+ * each, and each caller reports the note in its own response.
+ */
+const recoveries = new WeakMap();
+async function openRecoveryPage(context) {
+    const inFlight = recoveries.get(context);
+    if (inFlight) {
+        return await inFlight;
+    }
+    // Cleared as soon as it settles — on rejection as well as on success, so a
+    // failed recovery never poisons the entry: the next caller tries again.
+    const started = context.newPage().finally(() => {
+        recoveries.delete(context);
+    });
+    recoveries.set(context, started);
+    return await started;
+}
+/**
+ * The page a page-scoped tool should act on.
+ *
+ * Cheap on the happy path: the strict accessor answers it without listing pages
+ * or touching CDP, so only a selection that has actually gone costs anything.
+ */
+export async function resolveSelectedPage(context, response) {
+    try {
+        return context.getSelectedMcpPage();
+    }
+    catch {
+        // The selection is gone. The snapshot below is what can replace it.
+    }
+    await context.createPagesSnapshot();
+    try {
+        const selected = context.getSelectedMcpPage();
+        response?.appendResponseLine(`Note: the previously selected page was closed. Page ${selected.id} is now selected.`);
+        return selected;
+    }
+    catch {
+        // Still nothing to select: the browser has no pages at all.
+    }
+    const opened = await openRecoveryPage(context);
+    response?.appendResponseLine(`Note: the browser had no open pages, so a new one was opened. Page ${opened.id} is now selected.`);
+    return opened;
+}
+//# sourceMappingURL=pageRecovery.js.map