opera-devtools-mcp 0.2.4 → 0.4.0

package/build/src/tools/tools.js

@@ -5,6 +5,7 @@
  *
  * Modified by Opera Software AS.
  */
+import * as operaTools from '../opera/tools/opera.js';
 import * as consoleTools from './console.js';
 import * as emulationTools from './emulation.js';
 import * as extensionTools from './extensions.js';
@@ -12,9 +13,9 @@ import * as inputTools from './input.js';
 import * as lighthouseTools from './lighthouse.js';
 import * as memoryTools from './memory.js';
 import * as networkTools from './network.js';
-import * as operaTools from './opera.js';
 import * as pagesTools from './pages.js';
 import * as performanceTools from './performance.js';
+import * as pwaTools from './pwa.js';
 import * as screencastTools from './screencast.js';
 import * as screenshotTools from './screenshot.js';
 import * as scriptTools from './script.js';
@@ -36,6 +37,7 @@ export const createTools = (args) => {
             ...Object.values(operaTools),
             ...Object.values(pagesTools),
             ...Object.values(performanceTools),
+            ...Object.values(pwaTools),
             ...Object.values(screencastTools),
             ...Object.values(screenshotTools),
             ...Object.values(scriptTools),

package/build/src/tools/webmcp.js

@@ -15,7 +15,8 @@ export const listWebMcpTools = definePageTool({
     },
     schema: {},
     blockedByDialog: false,
-    handler: async (_request, response, _context) => {
+    verifyFilesSchema: {},
+    handler: async (_request, response) => {
         response.setListWebMcpTools();
     },
 });
@@ -34,6 +35,7 @@ export const executeWebMcpTool = definePageTool({
             .describe('The JSON-stringified parameters to pass to the WebMCP tool'),
     },
     blockedByDialog: false,
+    verifyFilesSchema: {},
     handler: async (request, response) => {
         const toolName = request.params.toolName;
         let input = {};

package/build/src/utils/WaitForHelper.js

@@ -0,0 +1,299 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { logger } from './logger.js';
+export class WaitForHelper {
+    #abortController = new AbortController();
+    #page;
+    #stableDomTimeout;
+    #stableDomFor;
+    #expectNavigationIn;
+    #navigationTimeout;
+    #dialogHandled = false;
+    /** Track all dialogs as they pause the renderer. */
+    #dialogDetected = false;
+    #initialUrl;
+    constructor(page, cpuTimeoutMultiplier, networkTimeoutMultiplier) {
+        this.#stableDomTimeout = 3000 * cpuTimeoutMultiplier;
+        this.#stableDomFor = 100 * cpuTimeoutMultiplier;
+        this.#expectNavigationIn = 100 * cpuTimeoutMultiplier;
+        this.#navigationTimeout = 3000 * networkTimeoutMultiplier;
+        this.#page = page;
+        this.#initialUrl = page.url();
+    }
+    /**
+     * A wrapper that executes a action and waits for
+     * a potential navigation, after which it waits
+     * for the DOM to be stable before returning.
+     */
+    async waitForStableDom() {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            // Bound the setup evaluation against the stable-DOM timeout. Without this
+            // cap a paused renderer (e.g. an open dialog) would make evaluateHandle
+            // hang until protocolTimeout (default 180s) while the tool mutex is held.
+            const stableDomObserver = __addDisposableResource(env_1, await Promise.race([
+                this.#page.evaluateHandle(timeout => {
+                    let timeoutId;
+                    function callback() {
+                        clearTimeout(timeoutId);
+                        timeoutId = setTimeout(() => {
+                            domObserver.resolver.resolve();
+                            domObserver.observer.disconnect();
+                        }, timeout);
+                    }
+                    const domObserver = {
+                        resolver: Promise.withResolvers(),
+                        observer: new MutationObserver(callback),
+                    };
+                    // It's possible that the DOM is not gonna change so we
+                    // need to start the timeout initially.
+                    callback();
+                    domObserver.observer.observe(document.body, {
+                        childList: true,
+                        subtree: true,
+                        attributes: true,
+                    });
+                    return domObserver;
+                }, this.#stableDomFor),
+                this.timeout(this.#stableDomTimeout),
+            ]).catch(() => undefined), false);
+            if (!stableDomObserver) {
+                return;
+            }
+            this.#abortController.signal.addEventListener('abort', async () => {
+                try {
+                    await stableDomObserver.evaluate(observer => {
+                        observer.observer.disconnect();
+                        observer.resolver.resolve();
+                    });
+                }
+                catch {
+                    // Ignored cleanup errors
+                }
+            });
+            return Promise.race([
+                stableDomObserver.evaluate(async (observer) => {
+                    return await observer.resolver.promise;
+                }),
+                this.timeout(this.#stableDomTimeout).then(() => {
+                    throw new Error('Timeout');
+                }),
+            ]);
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
+    timeout(time) {
+        return new Promise(res => {
+            const id = setTimeout(res, time);
+            this.#abortController.signal.addEventListener('abort', () => {
+                res();
+                clearTimeout(id);
+            });
+        });
+    }
+    async waitForEventsAfterAction(action, options) {
+        if (this.#abortController.signal.aborted) {
+            throw new Error("Can't re-use a WaitForHelper");
+        }
+        const dialogHandler = (dialog) => {
+            this.#dialogDetected = true;
+            if (!options?.handleDialog) {
+                return;
+            }
+            let actionToTake;
+            if (typeof options.handleDialog === 'object') {
+                actionToTake = options.handleDialog[dialog.type()];
+            }
+            else {
+                actionToTake = options.handleDialog;
+            }
+            if (actionToTake) {
+                this.#dialogHandled = true;
+                if (actionToTake === 'dismiss') {
+                    void dialog.dismiss();
+                }
+                else if (actionToTake === 'accept') {
+                    void dialog.accept();
+                }
+                else {
+                    void dialog.accept(actionToTake);
+                }
+            }
+        };
+        this.#page.on('dialog', dialogHandler);
+        this.#abortController.signal.addEventListener('abort', () => {
+            this.#page.off('dialog', dialogHandler);
+        });
+        // A scoped AbortController used to clean up navigation probe listeners.
+        // When aborted (either after navigation detection finishes or if this.#abortController
+        // aborts), it removes the CDP Page.frameStartedNavigating listener and automatically
+        // detaches the abort listener from this.#abortController.signal.
+        const navigationAbortController = new AbortController();
+        const navigationStartedResolvers = Promise.withResolvers();
+        const navigationListener = (event) => {
+            if (event.frameId !== this.#page.mainFrame()._id) {
+                return;
+            }
+            if (event.navigationType === 'sameDocument' ||
+                event.navigationType === 'historySameDocument') {
+                return;
+            }
+            navigationStartedResolvers.resolve(true);
+        };
+        this.#page._client().on('Page.frameStartedNavigating', navigationListener);
+        navigationAbortController.signal.addEventListener('abort', () => {
+            this.#page
+                ._client()
+                .off('Page.frameStartedNavigating', navigationListener);
+        });
+        this.#abortController.signal.addEventListener('abort', () => {
+            navigationStartedResolvers.resolve(false);
+            navigationAbortController.abort();
+        }, { signal: navigationAbortController.signal });
+        // Puppeteer's waitForNavigation must be started before the action runs so that
+        // it captures the pre-action loader ID. If started after the action triggers navigation,
+        // it risks recording the new loader ID and hanging until timeout.
+        // If no navigation occurs, this.#abortController will cancel it in the finally block.
+        const navigationFinished = this.#page
+            .waitForNavigation({
+            timeout: options?.timeout ?? this.#navigationTimeout,
+            signal: this.#abortController.signal,
+            ignoreSameDocumentNavigation: true,
+        })
+            .then(result => {
+            navigationStartedResolvers.resolve(true);
+            return result;
+        })
+            .catch(error => {
+            if (this.#abortController.signal.aborted ||
+                (error instanceof Error && error.name === 'AbortError')) {
+                return;
+            }
+            logger?.(error);
+        });
+        try {
+            await action();
+        }
+        catch (error) {
+            // Clear up pending promises
+            this.#abortController.abort();
+            throw error;
+        }
+        const expectNavigationIn = options?.expectNavigationIn ?? this.#expectNavigationIn;
+        const navigationStarted = await Promise.race([
+            navigationStartedResolvers.promise,
+            this.timeout(expectNavigationIn).then(() => {
+                navigationStartedResolvers.resolve(false);
+                return false;
+            }),
+        ]);
+        navigationAbortController.abort();
+        try {
+            // Only await navigation if one was actually initiated; otherwise, the
+            // pending waitForNavigation promise will be cancelled when this.#abortController aborts.
+            if (navigationStarted) {
+                await navigationFinished;
+            }
+            if (this.#dialogDetected) {
+                return this.#getResult();
+            }
+            // Wait for stable dom after navigation so we execute in
+            // the correct context
+            if (options?.waitForStableDom !== false) {
+                await this.waitForStableDom();
+            }
+        }
+        catch (error) {
+            logger?.(error);
+        }
+        finally {
+            this.#abortController.abort();
+        }
+        return this.#getResult();
+    }
+    #getResult() {
+        const urlAfterAction = this.#page.url();
+        return {
+            ...(urlAfterAction !== this.#initialUrl
+                ? { navigatedToUrl: urlAfterAction }
+                : {}),
+            dialogHandled: this.#dialogHandled,
+        };
+    }
+}
+export function getNetworkMultiplierFromString(condition) {
+    const puppeteerCondition = condition;
+    switch (puppeteerCondition) {
+        case 'Fast 4G':
+            return 1;
+        case 'Slow 4G':
+            return 2.5;
+        case 'Fast 3G':
+            return 5;
+        case 'Slow 3G':
+            return 10;
+    }
+    return 1;
+}
+//# sourceMappingURL=WaitForHelper.js.map

package/build/src/utils/check-for-updates.js

@@ -10,6 +10,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
+import { CACHE_DIR_NAME, ENV_NO_UPDATE_CHECKS } from '../opera/branding.js';
 import { VERSION } from '../version.js';
 /**
  * Notifies the user if an update is available.
@@ -21,11 +22,11 @@ export function resetUpdateCheckFlagForTesting() {
     isChecking = false;
 }
 export async function checkForUpdates(message) {
-    if (isChecking || process.env['OPERA_DEVTOOLS_NO_UPDATE_CHECKS']) {
+    if (isChecking || process.env[ENV_NO_UPDATE_CHECKS]) {
         return;
     }
     isChecking = true;
-    const cachePath = path.join(os.homedir(), '.cache', 'opera-devtools-mcp', 'latest.json');
+    const cachePath = path.join(os.homedir(), '.cache', CACHE_DIR_NAME, 'latest.json');
     let cachedVersion;
     let stats;
     try {
@@ -36,6 +37,10 @@ export async function checkForUpdates(message) {
     catch {
         // Ignore errors reading cache.
     }
+    // NOTE: upstream uses `semver.lt(VERSION, cachedVersion)` here. The fork
+    // deliberately compares for inequality, which also reports an "update" when
+    // the installed version is *newer* than the cached snapshot (e.g. after a
+    // downgrade or when running a local pre-release build).
     if (cachedVersion && cachedVersion !== VERSION) {
         console.warn(`\nUpdate available: ${VERSION} -> ${cachedVersion}\n${message}\n`);
     }
@@ -65,6 +70,7 @@ export async function checkForUpdates(message) {
         const child = child_process.spawn(process.execPath, [scriptPath, cachePath], {
             detached: true,
             stdio: 'ignore',
+            windowsHide: true,
         });
         child.unref();
     }

package/build/src/utils/files.js

@@ -11,8 +11,47 @@ export async function getTempFilePath(filename) {
     const filepath = path.join(dir, filename);
     return filepath;
 }
-export function ensureExtension(filepath, extension) {
-    const ext = path.extname(filepath);
-    return filepath.slice(0, filepath.length - ext.length) + extension;
+export async function resolveCanonicalPath(filePath) {
+    const absolutePath = path.resolve(filePath);
+    try {
+        // Get the true canonical path, resolving all symlinks.
+        return await fs.realpath(absolutePath);
+    }
+    catch (err) {
+        if (err &&
+            typeof err === 'object' &&
+            'code' in err &&
+            err.code === 'ENOENT') {
+            // Find the nearest existing ancestor directory on the filesystem.
+            let current = absolutePath;
+            const missingSegments = [];
+            while (true) {
+                const parent = path.dirname(current);
+                if (parent === current) {
+                    // Reached root directory but still couldn't resolve anything.
+                    throw err;
+                }
+                try {
+                    const canonicalParent = await fs.realpath(parent);
+                    return path.join(canonicalParent, path.basename(current), ...missingSegments);
+                }
+                catch (parentErr) {
+                    if (parentErr &&
+                        typeof parentErr === 'object' &&
+                        'code' in parentErr &&
+                        parentErr.code === 'ENOENT') {
+                        missingSegments.unshift(path.basename(current));
+                        current = parent;
+                    }
+                    else {
+                        throw parentErr;
+                    }
+                }
+            }
+        }
+        else {
+            throw err;
+        }
+    }
 }
 //# sourceMappingURL=files.js.map

package/build/src/utils/logger.js

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs';
+import util from 'node:util';
+const mcpDebugNamespace = 'mcp:log';
+let logFileStream;
+const _debugLog = util.debuglog(mcpDebugNamespace);
+export function saveLogsToFile(fileName) {
+    const logFile = fs.createWriteStream(fileName, { flags: 'a+' });
+    logFile.on('error', function (error) {
+        console.error(`Error when opening/writing to log file: ${error.message}`);
+        logFile.end();
+        process.exit(1);
+    });
+    logFileStream = logFile;
+    return logFile;
+}
+export function flushLogs(logFile, timeoutMs = 2000) {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(reject, timeoutMs);
+        logFile.end(() => {
+            clearTimeout(timeout);
+            resolve();
+        });
+    });
+}
+export const logger = (...args) => {
+    if (logFileStream) {
+        logFileStream.write(`${new Date().toISOString()} ${mcpDebugNamespace} ${util.format(...args)}\n`);
+    }
+    else if (_debugLog.enabled) {
+        _debugLog('%s %s', new Date().toISOString(), util.format(...args));
+    }
+};
+export const puppeteerLogger = (prefix) => {
+    if (logFileStream) {
+        return (...args) => {
+            logFileStream.write(`${new Date().toISOString()} ${prefix} ${util.format(...args)}\n`);
+        };
+    }
+    const dbg = util.debuglog(prefix);
+    return dbg.enabled
+        ? (...args) => {
+            dbg('%s %s', new Date().toISOString(), util.format(...args));
+        }
+        : undefined;
+};
+//# sourceMappingURL=logger.js.map

package/build/src/utils/polyfill.js

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DisposableStack, AsyncDisposableStack, SuppressedError, } from '../third_party/index.js';
+globalThis.DisposableStack ??= DisposableStack;
+globalThis.AsyncDisposableStack ??= AsyncDisposableStack;
+// @ts-expect-error Type mismatch between puppeteer-core and node for SuppressedError.
+globalThis.SuppressedError ??= SuppressedError;
+//# sourceMappingURL=polyfill.js.map

package/build/src/utils/url.js

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const ALLOWED_PROTOCOLS = new Set(['http:', 'https:', 'ws:', 'wss:']);
+const IPV4_LOOPBACK_REGEX = /^127(?:\.(?:25[0-5]|2[0-4]\d|[01]?\d\d?)){3}$/;
+/**
+ * Determines whether a given URL string points to a localhost / loopback address.
+ *
+ * @param url The URL string to test.
+ * @returns true if the URL is a valid network URL pointing to localhost or a loopback IP.
+ */
+export function isLocalhost(url) {
+    if (!url || typeof url !== 'string' || url.trim() === '') {
+        return false;
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
+        return false;
+    }
+    const hostname = parsed.hostname.toLowerCase().replace(/\.$/, '');
+    // 1. Check localhost and RFC 6761 *.localhost subdomains
+    if (hostname === 'localhost' || hostname.endsWith('.localhost')) {
+        return true;
+    }
+    // 2. Check IPv6 loopback ([::1] as returned by URL.hostname, or ::1)
+    if (hostname === '[::1]' || hostname === '::1') {
+        return true;
+    }
+    // 3. Check IPv4 loopback (127.0.0.0/8)
+    if (IPV4_LOOPBACK_REGEX.test(hostname)) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=url.js.map

package/build/src/version.js

@@ -5,8 +5,5 @@
  *
  * Modified by Opera Software AS.
  */
-// If moved update release-please config
-// x-release-please-start-version
-export const VERSION = '0.2.2';
-// x-release-please-end
+export const VERSION = '0.4.0';
 //# sourceMappingURL=version.js.map