opera-devtools-mcp 0.7.0 → 0.8.1

package/build/src/opera/daemonStreaming.js

@@ -0,0 +1,130 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+import { LoggingMessageNotificationSchema, PipeTransport, } from '../third_party/index.js';
+import { logger, puppeteerLogger } from '../utils/logger.js';
+import { daemonExitMessage } from './daemonLog.js';
+/** A streamed chunk frame, distinguished from the final response frame. */
+function isLogFrame(value) {
+    if (typeof value !== 'object' || value === null || !('log' in value)) {
+        return false;
+    }
+    return typeof value.log === 'string';
+}
+/** The live chunk sinks, keyed by the streaming token of their request. */
+const sinks = new Map();
+/**
+ * The streaming token a notification carries, if any.
+ *
+ * `_meta` is the protocol's own slot for per-request metadata of this kind
+ * (`RequestMetaSchema` is a loose object, so an extra key is legal on both the
+ * request and the notification), and a notification without one belongs to a
+ * caller that did not ask for streaming.
+ */
+function streamTokenOf(params) {
+    const meta = params._meta;
+    if (typeof meta !== 'object' || meta === null) {
+        return undefined;
+    }
+    const token = meta.streamToken;
+    return typeof token === 'string' ? token : undefined;
+}
+/**
+ * Forward `notifications/message` chunks to the sink of the request they
+ * belong to.
+ *
+ * `data` is a plain string (see `makeLogCallback`); anything else is some other
+ * logger's notification and is ignored rather than stringified into the user's
+ * terminal.
+ */
+export function attachLogForwarding(client) {
+    client.setNotificationHandler(LoggingMessageNotificationSchema, notification => {
+        const params = notification.params;
+        if (typeof params !== 'object' ||
+            params === null ||
+            !('data' in params) ||
+            typeof params.data !== 'string') {
+            return;
+        }
+        const token = streamTokenOf(params);
+        if (token === undefined) {
+            return;
+        }
+        sinks.get(token)?.(params.data);
+    });
+}
+/**
+ * Run `work` with the sink for `token` installed, and always remove it again —
+ * a sink left behind would push chunks from a *later* request onto a closed
+ * socket. Only this token's entry is removed, so a request that finishes never
+ * takes another request's streaming down with it.
+ */
+export async function withLogSink(token, sink, work) {
+    sinks.set(token, sink);
+    try {
+        return await work();
+    }
+    finally {
+        sinks.delete(token);
+    }
+}
+/**
+ * Read one response off one socket connection, streaming-aware: client side.
+ *
+ * With `onLog`, the request is marked `stream` and the connection stays open
+ * for the whole run: each `{log}` frame is handed to `onLog` as it arrives, and
+ * the promise settles on the final `DaemonResponse`. The timeout is re-armed by
+ * every chunk, so a long call that is actively producing output is never killed
+ * for being slow — only for going quiet.
+ *
+ * Without `onLog`, the original one-message-one-response protocol applies and
+ * the first frame is the answer, byte for byte as upstream's client reads it.
+ */
+export function requestOverSocket(options) {
+    const { socket, command, timeout, sessionId, onLog } = options;
+    // Only a tool call can produce chunks, so a `stop` or `status` that is
+    // handed a sink anyway is still sent on the original protocol.
+    const message = onLog !== undefined && command.method === 'invoke_tool'
+        ? { ...command, stream: true }
+        : command;
+    const { promise, resolve, reject } = Promise.withResolvers();
+    let timer;
+    const arm = () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            socket.destroy();
+            reject(new Error('Timeout waiting for daemon response'));
+        }, timeout);
+    };
+    arm();
+    const transport = new PipeTransport(socket, socket, puppeteerLogger);
+    transport.onmessage = (frame) => {
+        logger?.('onmessage', frame);
+        const parsed = JSON.parse(frame);
+        // A chunk frame is not the answer: hand it over and keep waiting.
+        if (onLog !== undefined && isLogFrame(parsed)) {
+            arm();
+            onLog(parsed.log);
+            return;
+        }
+        clearTimeout(timer);
+        resolve(parsed);
+    };
+    socket.on('error', error => {
+        clearTimeout(timer);
+        logger?.('Socket error:', error);
+        reject(error);
+    });
+    socket.on('close', () => {
+        clearTimeout(timer);
+        logger?.('Socket closed:');
+        reject(new Error(daemonExitMessage(sessionId)));
+    });
+    logger?.('Sending message', message);
+    transport.send(JSON.stringify(message));
+    return promise;
+}
+//# sourceMappingURL=daemonStreaming.js.map

package/build/src/opera/daemonToolCall.js

@@ -0,0 +1,26 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+import { operaAiTimeoutMs } from './streamingTools.js';
+/**
+ * Run one tool through the daemon's MCP client.
+ *
+ * `_meta` is the only per-request slot the MCP round trip preserves, which is
+ * what makes it the streaming token's carrier: the server echoes it on every
+ * `notifications/message` the tool emits, so a chunk can be routed back to the
+ * connection whose request produced it (`opera/daemonStreaming.ts`).
+ */
+export async function callDaemonTool(client, request) {
+    const timeout = operaAiTimeoutMs(request.tool);
+    return await client.callTool({
+        name: request.tool,
+        arguments: request.args ?? {},
+        ...(request.streamToken === undefined
+            ? {}
+            : { _meta: { streamToken: request.streamToken } }),
+    }, undefined, timeout === undefined ? undefined : { timeout });
+}
+//# sourceMappingURL=daemonToolCall.js.map

package/build/src/opera/detect.js

@@ -0,0 +1,114 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * Finding an installed browser. Ported from opera-browser-cli's `src/detect.ts`
+ * (Phase 1b). Opera Neon is preferred because it is the only build with the
+ * full Opera AI tool set; a plain Opera still gives `chat`. Anything else means
+ * the AI commands cannot work, which the caller reports rather than discovering
+ * halfway through a command.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export function neonCandidatePaths(platform = process.platform, home = '', env = process.env) {
+    if (platform === 'darwin') {
+        // `/Applications` is a literal macOS path; the `~/Applications` root is
+        // joined so it carries this host's separators, matching what a caller
+        // locating the same install with `path.join` builds. The pair is dropped
+        // for an empty home, where it would be the absolute paths over again.
+        return [
+            '/Applications/Opera Neon Developer.app/Contents/MacOS/Opera',
+            '/Applications/Opera Neon.app/Contents/MacOS/Opera',
+            ...(home === ''
+                ? []
+                : [
+                    join(home, 'Applications', 'Opera Neon Developer.app', 'Contents', 'MacOS', 'Opera'),
+                    join(home, 'Applications', 'Opera Neon.app', 'Contents', 'MacOS', 'Opera'),
+                ]),
+        ];
+    }
+    if (platform === 'win32') {
+        const localAppData = env.LOCALAPPDATA ?? `${home}\\AppData\\Local`;
+        const programFiles = env.PROGRAMFILES ?? 'C:\\Program Files';
+        return [
+            `${localAppData}\\Programs\\Opera Neon Developer\\opera.exe`,
+            `${programFiles}\\Opera Neon Developer\\opera.exe`,
+            `${localAppData}\\Programs\\Opera Neon\\opera.exe`,
+            `${programFiles}\\Opera Neon\\opera.exe`,
+        ];
+    }
+    // Opera Neon does not ship for Linux.
+    return [];
+}
+export function operaCandidatePaths(platform = process.platform, home = '', env = process.env) {
+    if (platform === 'darwin') {
+        return [
+            '/Applications/Opera GX.app/Contents/MacOS/Opera',
+            '/Applications/Opera.app/Contents/MacOS/Opera',
+            ...(home === ''
+                ? []
+                : [
+                    join(home, 'Applications', 'Opera GX.app', 'Contents', 'MacOS', 'Opera'),
+                    join(home, 'Applications', 'Opera.app', 'Contents', 'MacOS', 'Opera'),
+                ]),
+        ];
+    }
+    if (platform === 'win32') {
+        const localAppData = env.LOCALAPPDATA ?? `${home}\\AppData\\Local`;
+        const programFiles = env.PROGRAMFILES ?? 'C:\\Program Files';
+        return [
+            `${localAppData}\\Programs\\Opera GX\\opera.exe`,
+            `${localAppData}\\Programs\\Opera\\opera.exe`,
+            `${programFiles}\\Opera GX\\opera.exe`,
+            `${programFiles}\\Opera\\opera.exe`,
+        ];
+    }
+    return [];
+}
+/**
+ * Which Opera build an install path belongs to, judged by the directory the
+ * executable sits in. Matching whole install-directory names — rather than a
+ * substring anywhere in the path — keeps an unrelated directory that merely
+ * mentions a build (`/tmp/GX-tests/opera`) from being misreported.
+ */
+export function browserDisplayName(binPath) {
+    const dirs = binPath
+        .split(/[\\/]/)
+        .slice(0, -1)
+        .map(segment => segment.replace(/\.app$/, ''));
+    if (dirs.includes('Opera Neon Developer')) {
+        return 'Opera Neon Developer';
+    }
+    if (dirs.includes('Opera Neon')) {
+        return 'Opera Neon';
+    }
+    if (dirs.includes('Opera GX')) {
+        return 'Opera GX';
+    }
+    return 'Opera';
+}
+/** Every Opera install we can find, Neon first, each path reported once. */
+export function detectBrowsers(platform = process.platform, home = '', exists = existsSync, env = process.env) {
+    const neon = new Set(neonCandidatePaths(platform, home, env));
+    const found = [];
+    const seen = new Set();
+    for (const path of [...neon, ...operaCandidatePaths(platform, home, env)]) {
+        // A caller may pass a home whose `Applications` root is the same directory
+        // as `/Applications`; without this check the same install would be reported
+        // twice.
+        if (seen.has(path) || !exists(path)) {
+            continue;
+        }
+        seen.add(path);
+        found.push({ path, name: browserDisplayName(path), isNeon: neon.has(path) });
+    }
+    return found;
+}
+/** The browser to use when nobody has said which. */
+export function detectBrowser(platform = process.platform, home = '', exists = existsSync, env = process.env) {
+    return detectBrowsers(platform, home, exists, env)[0] ?? null;
+}
+//# sourceMappingURL=detect.js.map

package/build/src/opera/doctor.js

@@ -0,0 +1,317 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * `doctor` — the five checks that translate onto the daemon model, and the two
+ * repairs that need no decision from the user.
+ *
+ * Ported from opera-browser-cli's `src/cli.ts` `runDoctorChecks` /
+ * `runDoctorFixes`, filtered: the source's `bridge` check is subsumed by the
+ * daemon check here, its `mcp` check is about a binary this package *is*, and
+ * its `hooks` check is dropped with the hooks themselves. What remains is the
+ * configuration, the executable, the profile lock, the daemon, and the log.
+ *
+ * Nothing here ever fails the command: a failing check is a `fail` row, and the
+ * process still exits 0. The point of `doctor` is to report, not to gate.
+ */
+import { existsSync, readFileSync, renameSync, statSync } from 'node:fs';
+import { sendCommand } from '../daemon/client.js';
+import { isDaemonRunning } from '../daemon/utils.js';
+import { VERSION } from '../version.js';
+import { CLI_BIN_NAME } from './branding.js';
+import { encode, renderHelp, renderOutput } from './cliOutput.js';
+import { autoConfigure } from './config.js';
+import { readExitReason } from './daemonLifecycle.js';
+import { getDaemonLogPath, getPreviousDaemonLogPath } from './daemonLog.js';
+import { findUnknownConfigKeys, getConfigFile, readConfigFile, } from './envConfig.js';
+import { launcherMigrationNotice } from './launcherNotice.js';
+import { inspectProfileLock, probeDevToolsEndpoint, readDevToolsPort, } from './profile.js';
+/** Logs above this are rotated by `doctor --fix`. */
+const LOG_ROTATE_BYTES = 5 * 1024 * 1024;
+export function formatBytes(n) {
+    if (n < 1024) {
+        return `${n} B`;
+    }
+    if (n < 1024 * 1024) {
+        return `${(n / 1024).toFixed(1)} KB`;
+    }
+    return `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
+export function fileContainsMarker(path, marker) {
+    if (!existsSync(path)) {
+        return false;
+    }
+    try {
+        return readFileSync(path, 'utf-8').includes(marker);
+    }
+    catch {
+        return false;
+    }
+}
+/** The config file: absent is a warning, unknown keys are a warning, else ok. */
+function checkConfig() {
+    const configFile = getConfigFile();
+    if (!existsSync(configFile)) {
+        return {
+            name: 'config',
+            status: 'warn',
+            detail: `${configFile} not found — run \`${CLI_BIN_NAME} setup\``,
+        };
+    }
+    const config = readConfigFile(configFile);
+    const count = Object.keys(config).length;
+    const unknown = findUnknownConfigKeys(config);
+    if (unknown.length > 0) {
+        // A typo'd key is silently ignored at load time and looks perfectly correct
+        // in the file, so it has to be called out here or never.
+        const described = unknown
+            .map(u => u.suggestion ? `${u.key} (did you mean ${u.suggestion}?)` : u.key)
+            .join(', ');
+        return {
+            name: 'config',
+            status: 'warn',
+            detail: `${configFile} — unrecognised key${unknown.length === 1 ? '' : 's'}: ${described}`,
+        };
+    }
+    return {
+        name: 'config',
+        status: 'ok',
+        detail: `${configFile} (${count} var${count === 1 ? '' : 's'} set)`,
+    };
+}
+/** The Opera executable, unless an attach URL makes it unnecessary. */
+function checkExecutable() {
+    const execPath = process.env.OPERA_CLI_EXECUTABLE_PATH;
+    const browserUrl = process.env.OPERA_CLI_BROWSER_URL;
+    if (browserUrl) {
+        return {
+            name: 'executable',
+            status: 'ok',
+            detail: `OPERA_CLI_BROWSER_URL=${browserUrl} (skipping executable check)`,
+        };
+    }
+    if (!execPath) {
+        return {
+            name: 'executable',
+            status: 'warn',
+            detail: 'OPERA_CLI_EXECUTABLE_PATH not set — Opera AI commands will fail',
+        };
+    }
+    if (!existsSync(execPath)) {
+        return {
+            name: 'executable',
+            status: 'fail',
+            detail: `OPERA_CLI_EXECUTABLE_PATH=${execPath} does not exist`,
+        };
+    }
+    return { name: 'executable', status: 'ok', detail: execPath };
+}
+/** The persistent profile: free, in use and attachable, or in use and locked. */
+async function checkProfile() {
+    const profileDir = process.env.OPERA_CLI_USER_DATA_DIR;
+    if (!profileDir) {
+        return {
+            name: 'profile',
+            status: 'ok',
+            detail: 'isolated (no persistent profile configured)',
+        };
+    }
+    if (!existsSync(profileDir)) {
+        return {
+            name: 'profile',
+            status: 'ok',
+            detail: `${profileDir} (will be created on first launch)`,
+        };
+    }
+    const lock = inspectProfileLock(profileDir);
+    if (lock.state === 'free') {
+        return { name: 'profile', status: 'ok', detail: `${profileDir} (free)` };
+    }
+    const port = readDevToolsPort(profileDir);
+    const live = port !== null ? await probeDevToolsEndpoint(port) : null;
+    if (live) {
+        return {
+            name: 'profile',
+            status: 'ok',
+            detail: `in use by ${live.browser}, attachable on port ${port}`,
+        };
+    }
+    return {
+        name: 'profile',
+        status: 'warn',
+        detail: `in use${lock.pid ? ` by pid ${lock.pid}` : ''} with no debugging port — a separate profile will be used`,
+    };
+}
+/** The daemon: not running, running, or running a different version. */
+async function checkDaemon(sessionId) {
+    if (!isDaemonRunning(sessionId)) {
+        const reason = readExitReason(sessionId);
+        return {
+            name: 'daemon',
+            status: 'warn',
+            detail: reason
+                ? `not running (last exit: ${reason})`
+                : 'not running (will auto-start on first command)',
+        };
+    }
+    try {
+        const response = await sendCommand({ method: 'status' }, sessionId);
+        if (!response.success) {
+            return {
+                name: 'daemon',
+                status: 'fail',
+                detail: `running but ${String(response.error)}`,
+            };
+        }
+        const data = JSON.parse(response.result);
+        if (data.version !== VERSION) {
+            return {
+                name: 'daemon',
+                status: 'warn',
+                detail: `running ${data.version}, but this CLI is ${VERSION} — restarts automatically on next command`,
+            };
+        }
+        return {
+            name: 'daemon',
+            status: 'ok',
+            detail: `running ${data.version}, pid ${data.pid}, socket ${data.socketPath}`,
+        };
+    }
+    catch (error) {
+        return {
+            name: 'daemon',
+            status: 'fail',
+            detail: `running but not answering: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/** The daemon log, which is where a daemon that died without a reason explains itself. */
+function checkLogs(sessionId) {
+    const logFile = getDaemonLogPath(sessionId);
+    if (!existsSync(logFile)) {
+        return {
+            name: 'logs',
+            status: 'warn',
+            detail: `${logFile} not yet created`,
+        };
+    }
+    try {
+        const size = statSync(logFile).size;
+        return {
+            name: 'logs',
+            status: 'ok',
+            detail: `${logFile} (${formatBytes(size)})`,
+            bytes: size,
+        };
+    }
+    catch {
+        return {
+            name: 'logs',
+            status: 'warn',
+            detail: `${logFile} exists but cannot stat`,
+        };
+    }
+}
+export async function runDoctorChecks(sessionId) {
+    return [
+        checkConfig(),
+        checkExecutable(),
+        await checkProfile(),
+        await checkDaemon(sessionId),
+        checkLogs(sessionId),
+    ];
+}
+/**
+ * Rotate the daemon log out of the way, one generation.
+ *
+ * The daemon does this itself on startup (`openDaemonLog`), but a session that
+ * stays up for weeks never restarts, so `--fix` does it explicitly. Renaming a
+ * file the daemon still holds open is safe on POSIX: the daemon keeps writing
+ * to the renamed inode until its next open. On Windows the rename would fail
+ * against a live handle, so there it is skipped and reported.
+ */
+function rotateDaemonLog(sessionId) {
+    const logFile = getDaemonLogPath(sessionId);
+    if (process.platform === 'win32' && isDaemonRunning(sessionId)) {
+        return false;
+    }
+    try {
+        renameSync(logFile, getPreviousDaemonLogPath(sessionId));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Repair what can be repaired mechanically. Anything needing a decision — an
+ * install, a config edit — is reported, never done on the user's behalf.
+ */
+export async function runDoctorFixes(checks, sessionId) {
+    const done = [];
+    const config = checks.find(check => check.name === 'config');
+    if (config && config.detail.includes('not found')) {
+        const result = autoConfigure();
+        if (result.status === 'configured') {
+            done.push(`wrote a config for ${result.browser.name}`);
+        }
+    }
+    const logs = checks.find(check => check.name === 'logs');
+    if (logs?.bytes !== undefined && logs.bytes >= LOG_ROTATE_BYTES) {
+        done.push(rotateDaemonLog(sessionId)
+            ? 'rotated the daemon log'
+            : 'could not rotate the daemon log (it is held open)');
+    }
+    return done;
+}
+function summarize(checks) {
+    return {
+        ok: checks.filter(check => check.status === 'ok').length,
+        warn: checks.filter(check => check.status === 'warn').length,
+        fail: checks.filter(check => check.status === 'fail').length,
+    };
+}
+function renderChecks(checks) {
+    return `checks[${checks.length}]:\n${checks
+        .map(check => `  ${check.name}: ${check.status} (${check.detail})`)
+        .join('\n')}`;
+}
+export async function handleDoctor(args, sessionId) {
+    if (args.includes('--fix')) {
+        const applied = await runDoctorFixes(await runDoctorChecks(sessionId), sessionId);
+        const after = await runDoctorChecks(sessionId);
+        const summary = { fixed: applied.length, ...summarize(after) };
+        return renderOutput([
+            await encode({ doctor: summary }),
+            applied.length > 0
+                ? `fixed[${applied.length}]:\n${applied.map(line => `  ${line}`).join('\n')}`
+                : 'fixed: nothing needed repairing',
+            renderChecks(after),
+            launcherMigrationNotice(),
+        ]);
+    }
+    const checks = await runDoctorChecks(sessionId);
+    const help = [];
+    if (checks.some(check => check.name === 'config' && check.status !== 'ok')) {
+        help.push(`Run \`${CLI_BIN_NAME} setup\` to write a config file`);
+    }
+    if (checks.some(check => check.name === 'executable' && check.status !== 'ok')) {
+        help.push(`Run \`${CLI_BIN_NAME} setup\` to detect Opera, or set OPERA_CLI_EXECUTABLE_PATH`);
+    }
+    if (checks.some(check => check.name === 'profile' && check.status === 'warn')) {
+        help.push('A profile in use with no debugging port cannot be attached to — the CLI will use a separate one');
+    }
+    if (checks.some(check => check.name === 'daemon' && check.status === 'fail')) {
+        help.push(`Run \`${CLI_BIN_NAME} logs\` to see why the daemon is unhealthy`);
+    }
+    return renderOutput([
+        await encode({ doctor: summarize(checks) }),
+        renderChecks(checks),
+        help.length > 0 ? renderHelp(help) : '',
+        launcherMigrationNotice(),
+    ]);
+}
+//# sourceMappingURL=doctor.js.map