opera-devtools-mcp 0.7.0 → 0.8.0

package/build/src/opera/envConfig.js

@@ -0,0 +1,229 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { STATE_DIR_NAME } from './branding.js';
+/**
+ * The five `OPERA_CLI_*` variables the fork recognises. Ported from
+ * opera-browser-cli's `KNOWN_CONFIG_KEYS` and filtered to Phase 1a scope —
+ * `PORT`, `MCP_BIN`, `ENABLE_HOOKS`, `TAKEOVER` and `DEV` are dropped or
+ * deferred to feature-owning phases. Also the promotion allowlist: only these
+ * keys may reach `process.env`, so a typo (or a stray `NODE_OPTIONS`) in the
+ * config file cannot silently become part of the daemon's environment.
+ */
+export const KNOWN_CONFIG_KEYS = [
+    'OPERA_CLI_EXECUTABLE_PATH',
+    'OPERA_CLI_BROWSER_URL',
+    'OPERA_CLI_USER_DATA_DIR',
+    'OPERA_CLI_HEADED',
+    'OPERA_CLI_CHROME_ARGS',
+];
+/** `~/.opera-browser-cli`, derived from the branding constant. */
+export function getStateDir(home = homedir()) {
+    return join(home, STATE_DIR_NAME);
+}
+/** `~/.opera-browser-cli/config`, derived from the branding constant. */
+export function getConfigFile(home = homedir()) {
+    return join(getStateDir(home), 'config');
+}
+/** Module-load snapshot of `getConfigFile()`; `readConfigFile` defaults to it. */
+const DEFAULT_CONFIG_FILE = getConfigFile();
+/**
+ * Strip a matching quote pair and unescape the escaped quotes inside it.
+ * Ported verbatim from opera-browser-cli's `parseConfigValue`.
+ */
+export function parseConfigValue(raw) {
+    if ((raw.startsWith('"') && raw.endsWith('"')) ||
+        (raw.startsWith("'") && raw.endsWith("'"))) {
+        return raw.slice(1, -1).replace(/\\"/g, '"').replace(/\\'/g, "'");
+    }
+    return raw;
+}
+/** Levenshtein distance, capped — only used to suggest a corrected key. */
+function editDistance(a, b) {
+    const rows = a.length + 1;
+    const cols = b.length + 1;
+    let prev = Array.from({ length: cols }, (_, i) => i);
+    for (let i = 1; i < rows; i++) {
+        const curr = [i, ...Array(cols - 1).fill(0)];
+        for (let j = 1; j < cols; j++) {
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = curr;
+    }
+    return prev[cols - 1];
+}
+/** Config keys this program does not read, with a likely intended key where obvious. */
+export function findUnknownConfigKeys(config) {
+    const unknown = [];
+    for (const key of Object.keys(config)) {
+        if (KNOWN_CONFIG_KEYS.includes(key)) {
+            continue;
+        }
+        let best = null;
+        let bestDistance = Number.POSITIVE_INFINITY;
+        for (const candidate of KNOWN_CONFIG_KEYS) {
+            const distance = editDistance(key, candidate);
+            if (distance < bestDistance) {
+                bestDistance = distance;
+                best = candidate;
+            }
+        }
+        const tolerance = Math.max(4, Math.ceil(key.length / 3));
+        unknown.push({ key, suggestion: bestDistance <= tolerance ? best : null });
+    }
+    return unknown;
+}
+/**
+ * Read the config file as KEY=VALUE lines. `#` comments and blank lines are
+ * skipped, along with lines without a `=`; an unreadable or missing file reads
+ * as `{}` — config is a cache, never a prerequisite.
+ *
+ * `filePath` exists only as a test seam; production callers use the default.
+ */
+export function readConfigFile(filePath = DEFAULT_CONFIG_FILE) {
+    const config = {};
+    try {
+        for (const line of readFileSync(filePath, 'utf-8').split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#')) {
+                continue;
+            }
+            const eq = trimmed.indexOf('=');
+            if (eq === -1) {
+                continue;
+            }
+            config[trimmed.slice(0, eq).trim()] = parseConfigValue(trimmed.slice(eq + 1).trim());
+        }
+    }
+    catch {
+        // Unreadable or missing config is treated as absent — never fail a command over it.
+    }
+    return config;
+}
+/**
+ * Promote the recognised config-file entries into `process.env`, only where the
+ * variable is not already set (so environment beats config). Unrecognised keys
+ * are never promoted — the file is user-writable data, and handing it arbitrary
+ * environment variables (a stray `NODE_OPTIONS`, say) would let it steer the
+ * daemon the CLI spawns. They warn instead: once per unrecognised key per call,
+ * with the closest suggestion. Never fails a run.
+ */
+export function loadOperaCliConfig(filePath = DEFAULT_CONFIG_FILE) {
+    const config = readConfigFile(filePath);
+    for (const [key, value] of Object.entries(config)) {
+        if (KNOWN_CONFIG_KEYS.includes(key) &&
+            !(key in process.env)) {
+            process.env[key] = value;
+        }
+    }
+    for (const { key, suggestion } of findUnknownConfigKeys(config)) {
+        console.error(suggestion
+            ? `Warning: unknown config key "${key}" — did you mean "${suggestion}"?`
+            : `Warning: unknown config key "${key}".`);
+    }
+}
+/** True when any of `flags` (bare or `=value` form) already appears on argv. */
+function hasArg(argv, ...flags) {
+    return argv.some(arg => flags.some(flag => arg === flag || arg.startsWith(`${flag}=`)));
+}
+/**
+ * Default Chromium arguments Puppeteer injects that must be reverted when
+ * launching Opera against a persistent profile. Ported from
+ * opera-browser-cli's `buildTransportArgs()`: a mocked keychain and
+ * `--password-store=basic` stop the browser decrypting the real Keychain (so
+ * the profile launches logged out), while the component-extension and
+ * background default blockers stop the Opera AI extension from loading (so
+ * `Opera.dispatchAction` has "no target" to dispatch to).
+ */
+export const PERSISTENT_PROFILE_IGNORE_DEFAULT_ARGS = [
+    '--use-mock-keychain',
+    '--password-store=basic',
+    '--disable-extensions',
+    '--disable-component-extensions-with-background-pages',
+    '--disable-default-apps',
+    '--disable-background-networking',
+];
+/**
+ * Translate `OPERA_CLI_*` env vars into the equivalent yargs flags and append
+ * them to `argv`, only when the flag was not already passed on the command
+ * line (so an explicit flag beats the environment). Replaces
+ * opera-browser-cli's `buildTransportArgs`, which emitted the same mapping as
+ * bridge spawn args rather than argv.
+ */
+export function applyEnvToArgv(argv) {
+    const env = process.env;
+    // The CLI never routes by pageId (it replaces the retired opera-browser-cli).
+    // Only CLI-spawned sessions — not direct MCP clients — disable routing on the
+    // server.
+    if (argv.includes('--viaCli') && !hasArg(argv, '--no-page-id-routing')) {
+        argv.push('--no-page-id-routing');
+    }
+    const headed = env.OPERA_CLI_HEADED?.trim();
+    if (headed && !hasArg(argv, '--headless', '--no-headless')) {
+        if (headed === '1' || headed.toLowerCase() === 'true') {
+            argv.push('--headless=false');
+        }
+        else if (headed === '0' || headed.toLowerCase() === 'false') {
+            argv.push('--headless=true');
+        }
+        else {
+            // `true`/`false` are natural spellings; anything else is a typo that
+            // would otherwise be dropped without a trace.
+            console.error(`Warning: ignoring OPERA_CLI_HEADED="${env.OPERA_CLI_HEADED}" — expected 1, 0, true, or false.`);
+        }
+    }
+    const chromeArgs = env.OPERA_CLI_CHROME_ARGS;
+    if (chromeArgs?.trim() && !hasArg(argv, '--chromeArg', '--chrome-arg')) {
+        for (const arg of chromeArgs.trim().split(/\s+/)) {
+            argv.push(`--chromeArg=${arg}`);
+        }
+    }
+    const browserUrl = env.OPERA_CLI_BROWSER_URL;
+    if (browserUrl && !hasArg(argv, '--browserUrl', '--browser-url', '-u')) {
+        argv.push(`--browserUrl=${browserUrl}`);
+    }
+    // Attaching to an already-running browser (by URL or WS endpoint) means the
+    // browser lifecycle is managed externally. `--userDataDir` and
+    // `--executablePath` both conflict with a browser URL/WS endpoint in yargs
+    // (see `browserOptions.conflicts`), so injecting either from config here
+    // aborts argument parsing — the "Arguments userDataDir and browserUrl are
+    // mutually exclusive" crash. Mirror opera-browser-cli's `buildTransportArgs`:
+    // a browser URL wins and the profile/executable flags are skipped entirely.
+    const attachesToBrowser = hasArg(argv, '--browserUrl', '--browser-url', '-u', '--wsEndpoint', '--ws-endpoint', '-w');
+    // A persistent profile overrides isolated mode, and `--userDataDir` is
+    // mutually exclusive with `--isolated` in yargs — so emit the dir alone, plus
+    // the companion flags ported from opera-browser-cli's `buildTransportArgs()`
+    // (drop the Puppeteer defaults that block Keychain decryption and extension
+    // loading, and load the Opera AI component extension explicitly).
+    const userDataDir = env.OPERA_CLI_USER_DATA_DIR;
+    if (userDataDir &&
+        !attachesToBrowser &&
+        // An explicit `--isolated` asks for a throwaway profile, and yargs treats
+        // the two as mutually exclusive. The CLI wins here as it does everywhere
+        // else in this file: injecting the configured dir alongside `--isolated`
+        // made the MCP server exit during argument parsing ("Connection closed" to
+        // the daemon, which then tore down), and the next command silently started
+        // a daemon on the persistent profile instead.
+        !hasArg(argv, '--isolated') &&
+        !hasArg(argv, '--userDataDir', '--user-data-dir')) {
+        argv.push(`--userDataDir=${userDataDir}`);
+        for (const flag of PERSISTENT_PROFILE_IGNORE_DEFAULT_ARGS) {
+            argv.push(`--ignoreDefaultChromeArg=${flag}`);
+        }
+        argv.push('--chromeArg=--show-component-extension-options');
+    }
+    const executablePath = env.OPERA_CLI_EXECUTABLE_PATH;
+    if (executablePath &&
+        !attachesToBrowser &&
+        !hasArg(argv, '--autoConnect', '--auto-connect') &&
+        !hasArg(argv, '--executablePath', '--executable-path', '-e')) {
+        argv.push(`--executablePath=${executablePath}`);
+    }
+}
+//# sourceMappingURL=envConfig.js.map

package/build/src/opera/launcherNotice.js

@@ -0,0 +1,116 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * What to tell a user whose CLI was delivered by the compatibility launcher.
+ *
+ * `opera-browser-cli@0.1.55` is a launcher: it declares the old package name
+ * and the old bin name, depends on this package, and spawns this CLI. That is
+ * how a habit-driven `npm i -g opera-browser-cli` (or `npm update -g
+ * opera-browser-cli`) picks up the new implementation without `--force` and
+ * without a manual uninstall — npm only retires a foreign binstub on a
+ * same-name upgrade.
+ *
+ * The end state removes the launcher again, and the user has to be told how:
+ * npm has no `replaces` field, and an install-time script is blocked by
+ * npm ≥12's `allowScripts` gate by default. The launcher therefore marks its
+ * child with `OPERA_CLI_LAUNCHER=1` (and passes the prefix it resolved as
+ * `OPERA_CLI_LAUNCHER_PREFIX`, for support), and both `--version` and `doctor`
+ * — the two commands a stuck user runs — print the retirement recipes when the
+ * marker is set.
+ *
+ * The other direction has no marker to react to: a user who installed this
+ * package next to the *pre-launcher* `opera-browser-cli` never runs this CLI at
+ * all, they run the old one. `notifyLegacyPackageInstalled` covers that case
+ * from the runtime guard, and is the only notice here that reads the filesystem.
+ *
+ * The recipes are printed verbatim so they can be pasted; a release that
+ * publishes the tombstone has to change the text here (see
+ * `docs/npm-package-transition.md`).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveGlobalPrefix, warn } from './migrationShared.js';
+/** Marker the launcher's `bin/cli.js` sets to `1` before it spawns this CLI. */
+const LAUNCHER_ENV = 'OPERA_CLI_LAUNCHER';
+/**
+ * Say one line if the pre-launcher `opera-browser-cli` is still installed.
+ *
+ * Called from the runtime migration guard (`legacyBridgeCleanup`), because the
+ * install hook this used to run in is blocked by npm ≥12's `allowScripts` gate.
+ * The check is a filesystem read rather than `npm ls -g`, which would spawn a
+ * second npm that contends on the arborist lock npm 7+ holds during a global
+ * install — observed to hang on npm 9 and 10. The old package is never
+ * uninstalled from here for the same reason: the user is pointed at the command
+ * instead.
+ *
+ * Two of the package's releases are the migration working as intended and must
+ * not be reported, because `npm i -g opera-browser-cli@latest` would install
+ * exactly what is already there:
+ *
+ *   - `0.1.55`, the compatibility launcher that delivered this install,
+ *     recognised by its `bin/cli.js` marker;
+ *   - `0.2.0`, the bin-less tombstone that retires the launcher, recognised by
+ *     version (`0.2.0` is the first release without a bin).
+ *
+ * What remains at that path — an older `0.1.x`, or a hand-copied file — is what
+ * this notice is for.
+ */
+export function notifyLegacyPackageInstalled() {
+    try {
+        const prefix = resolveGlobalPrefix();
+        if (prefix === null) {
+            return;
+        }
+        const candidates = [
+            path.join(prefix, 'lib', 'node_modules', 'opera-browser-cli'),
+            path.join(prefix, 'node_modules', 'opera-browser-cli'),
+        ];
+        const installed = candidates.find(dir => fs.existsSync(path.join(dir, 'package.json')));
+        if (installed === undefined) {
+            return;
+        }
+        if (fs.existsSync(path.join(installed, 'bin', 'cli.js'))) {
+            return;
+        }
+        let version = '';
+        try {
+            const manifest = JSON.parse(fs.readFileSync(path.join(installed, 'package.json'), 'utf-8'));
+            version = typeof manifest.version === 'string' ? manifest.version : '';
+        }
+        catch {
+            // Unreadable reads as pre-launcher: the status quo this notice is for.
+        }
+        const [major = 0, minor = 0] = version.split('.').map(part => Number(part));
+        if (major > 0 || (major === 0 && minor >= 2)) {
+            return;
+        }
+        warn(`opera-devtools-mcp: legacy opera-browser-cli detected at ${installed}; run: npm i -g opera-browser-cli@latest to migrate.`);
+    }
+    catch {
+        // A notice that cannot be composed must not be the thing that breaks a start.
+    }
+}
+/**
+ * The recipes that retire the launcher, or the empty string when this CLI was
+ * not launched by it — callers join the result into their output and never have
+ * to branch.
+ */
+export function launcherMigrationNotice() {
+    if (process.env[LAUNCHER_ENV] !== '1') {
+        return '';
+    }
+    return [
+        'Notice: this CLI was launched via the compatibility launcher (opera-browser-cli@0.1.55).',
+        'To complete migration, run either:',
+        '  npm i -g opera-devtools-mcp@latest opera-browser-cli@latest',
+        '    (then optionally: npm rm -g opera-browser-cli)',
+        '  — or —',
+        '  npm rm -g opera-browser-cli',
+        '  npm i -g opera-devtools-mcp@latest',
+    ].join('\n');
+}
+//# sourceMappingURL=launcherNotice.js.map

package/build/src/opera/legacyBridgeCleanup.js

@@ -0,0 +1,297 @@
+/**
+ * @license
+ * Copyright 2026 Opera Norway AS. All rights reserved.
+ *
+ * This file is an original work developed by Opera.
+ */
+/**
+ * Stop the legacy `opera-browser-cli` HTTP bridge.
+ *
+ * Before the two packages were merged, `opera-browser-cli` ran an HTTP bridge
+ * that held port 9225 (scanning up to 9234) and wrote its identity to
+ * `~/.opera-browser-cli/bridge.pid`. A user upgrading to `opera-devtools-mcp`
+ * may still have that bridge running, holding a browser and a stdio child of
+ * the old MCP server. The new CLI speaks to a Unix-socket daemon instead, so a
+ * surviving bridge is a resource leak and a confusing second `opera-browser-cli`
+ * in `ps` — this module removes it.
+ *
+ * Nothing here runs at install time. npm ≥12 blocks install scripts unless the
+ * user opts in with a flag nobody types, so the cleanup lives where it always
+ * executes: `runLegacyMigrationGuard` is awaited by both entry points — the CLI
+ * bin (`opera-browser-cli`) and the MCP bin (`opera-devtools-mcp`), which an MCP
+ * client starts on its own, with no CLI invocation anywhere.
+ *
+ * Two rules govern which process may be signalled, both lifted from the old
+ * client's own identity contract: a PID is only trusted when its PID file also
+ * records *this* boot (a recycled PID after a reboot must never be killed), and
+ * a bridge answering `/health` is trusted by that answer alone. Port probing and
+ * the PID file are therefore two independent ways to recognise the same bridge,
+ * and neither ever signals a process it has not identified.
+ *
+ * The legacy CLI starts its bridge `detached`, which makes the bridge a process
+ * group leader whose browser and stdio MCP child share its group. Every signal
+ * goes to that group: a bridge that ignores SIGTERM is SIGKILLed, and its exit
+ * handler — the one that group-kills its children — never runs on SIGKILL.
+ */
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { getRuntimeHome } from '../daemon/utils.js';
+import { STATE_DIR_NAME } from './branding.js';
+import { notifyLegacyPackageInstalled } from './launcherNotice.js';
+import { getEffectiveHome, isMigrationActive, isProcessAlive, terminateProcess, warn, } from './migrationShared.js';
+/** Port the legacy bridge prefers, and how many consecutive ports it scans. */
+export const LEGACY_DEFAULT_PORT = 9225;
+export const LEGACY_PORT_SCAN_COUNT = 10;
+/** What the legacy bridge names itself in its `/health` payload. */
+const LEGACY_SERVER_NAME = 'opera-browser-cli';
+const HEALTH_TIMEOUT_MS = 2_000;
+/** `~/.opera-browser-cli/bridge.pid` (or `<home>/.opera-browser-cli/bridge.pid`). */
+export function getLegacyPidFilePath(home = os.homedir()) {
+    return path.join(home, STATE_DIR_NAME, 'bridge.pid');
+}
+/**
+ * The ports the legacy bridge may live on, in preference order. Reads the same
+ * `OPERA_CLI_PORT` override the old client honoured.
+ */
+export function legacyCandidatePorts() {
+    const base = Number.parseInt(process.env.OPERA_CLI_PORT ?? String(LEGACY_DEFAULT_PORT), 10);
+    const start = Number.isFinite(base) ? base : LEGACY_DEFAULT_PORT;
+    return Array.from({ length: LEGACY_PORT_SCAN_COUNT }, (_, i) => start + i);
+}
+/**
+ * The instant this machine booted, in whole minutes since the epoch, or null
+ * when the process cannot ask — some sandboxes deny the `uptime` syscall.
+ * A null answer means "cannot verify this boot", which is a refusal to signal,
+ * not a reason to fail.
+ */
+function computeBootMinute(nowMs = Date.now()) {
+    try {
+        return Math.floor((nowMs - os.uptime() * 1000) / 60_000);
+    }
+    catch {
+        return null;
+    }
+}
+function readLegacyPidFile(home) {
+    try {
+        const data = JSON.parse(fs.readFileSync(getLegacyPidFilePath(home), 'utf-8'));
+        if (typeof data.pid === 'number' && typeof data.port === 'number') {
+            return data;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function removeLegacyPidFile(home) {
+    try {
+        fs.rmSync(getLegacyPidFilePath(home), { force: true });
+    }
+    catch {
+        // Best-effort: a PID file we cannot remove is not worth failing the install.
+    }
+}
+/** The one notice both stop paths print before signalling a bridge. */
+function legacyStopWarning(pid) {
+    return `opera-devtools-mcp: stopping legacy HTTP bridge (pid ${pid}) for migration — any active browser session will be interrupted.`;
+}
+/**
+ * Stop the bridge the PID file names, if it names a live one from this boot.
+ *
+ * This is the CLI's fast path: one file read, no network. It never throws — the
+ * CLI calls it before every command, and a migration convenience must not be
+ * able to break a working CLI — so anything unexpected reads as "nothing to
+ * do". A PID file that names a dead process, or one stamped with a different
+ * boot, is cleaned up but never signalled; the port probe is the only way to
+ * identify that bridge safely.
+ */
+export async function stopLegacyBridge(options = {}) {
+    try {
+        const home = options.home ?? os.homedir();
+        const info = readLegacyPidFile(home);
+        if (info === null) {
+            return false;
+        }
+        if (!isProcessAlive(info.pid)) {
+            removeLegacyPidFile(home);
+            return false;
+        }
+        const bootMinute = computeBootMinute();
+        const fromThisBoot = typeof info.bootMinute === 'number' &&
+            bootMinute !== null &&
+            Math.abs(info.bootMinute - bootMinute) <= 1;
+        if (!fromThisBoot) {
+            // An unverifiable PID may be a stranger's after a reboot. Leave the file
+            // so the port probe can identify the bridge by its `/health` answer.
+            return false;
+        }
+        warn(legacyStopWarning(info.pid));
+        const gone = await terminateProcess(info.pid, { group: true });
+        if (gone) {
+            removeLegacyPidFile(home);
+        }
+        return gone;
+    }
+    catch {
+        return false;
+    }
+}
+/** One HTTP GET, resolving to the body or null on any error or timeout. */
+function httpGetHealth(port) {
+    const { promise, resolve } = Promise.withResolvers();
+    const req = http.request({
+        hostname: '127.0.0.1',
+        port,
+        path: '/health',
+        method: 'GET',
+        timeout: HEALTH_TIMEOUT_MS,
+    }, res => {
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', chunk => {
+            body += chunk;
+        });
+        res.on('end', () => resolve(body));
+        res.on('error', () => resolve(null));
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => {
+        req.destroy();
+        resolve(null);
+    });
+    req.end();
+    return promise;
+}
+/**
+ * Probe the candidate ports and stop every bridge of ours that answers.
+ *
+ * Used on install, where the bridge's PID file may be missing or root-owned and
+ * `/health` is the only remaining identity. A response is ours when its `server`
+ * field says so; its `pid` is then the process to stop, falling back to a live
+ * PID file that names the same port.
+ */
+export async function probeAndStopLegacyBridges(ports, options = {}) {
+    try {
+        const home = options.home ?? os.homedir();
+        const fileInfo = readLegacyPidFile(home);
+        const probes = await Promise.all(ports.map(async (port) => {
+            const body = await httpGetHealth(port);
+            if (body === null) {
+                return null;
+            }
+            try {
+                const record = JSON.parse(body);
+                if (record.server !== LEGACY_SERVER_NAME) {
+                    return null;
+                }
+                return {
+                    port,
+                    pid: typeof record.pid === 'number' ? record.pid : 0,
+                };
+            }
+            catch {
+                return null;
+            }
+        }));
+        let stopped = false;
+        for (const probe of probes) {
+            if (probe === null) {
+                continue;
+            }
+            const pid = probe.pid > 0
+                ? probe.pid
+                : fileInfo &&
+                    fileInfo.port === probe.port &&
+                    isProcessAlive(fileInfo.pid)
+                    ? fileInfo.pid
+                    : null;
+            if (pid === null || !isProcessAlive(pid)) {
+                continue;
+            }
+            warn(legacyStopWarning(pid));
+            stopped = (await terminateProcess(pid, { group: true })) || stopped;
+        }
+        if (fileInfo !== null && !isProcessAlive(fileInfo.pid)) {
+            removeLegacyPidFile(home);
+        }
+        return stopped;
+    }
+    catch {
+        return false;
+    }
+}
+/** The file that records the boot this user's boot-scoped pass already ran in. */
+const BOOT_SCOPED_PASS_FILE = 'legacy-guard';
+/**
+ * Claim the once-per-boot pass, and say whether this call owns it.
+ *
+ * The pass probes the bridge's port window, which is the only way to identify a
+ * bridge whose PID file is missing, unreadable (it is mode 0600, so another user
+ * cannot read it), or stamped with a boot this process cannot verify. That is
+ * network I/O and a possible kill, so it happens at most once per boot per user
+ * rather than on every command and every MCP server start.
+ *
+ * The recorded stamp is the boot instant, exactly as in the bridge's own PID
+ * file, so a stale marker cannot outlive a reboot — `/tmp` is not guaranteed to
+ * be cleared on macOS, and the marker may also live under `XDG_RUNTIME_DIR`.
+ * A marker that cannot be written, or a boot that cannot be computed, claims the
+ * pass: a repeated probe is cheap, skipping the cleanup is not.
+ */
+function claimBootScopedPass() {
+    const marker = path.join(getRuntimeHome(''), BOOT_SCOPED_PASS_FILE);
+    let recorded = null;
+    try {
+        const text = fs.readFileSync(marker, 'utf-8');
+        recorded = Number.parseInt(text, 10);
+    }
+    catch {
+        // No marker yet, or one we cannot read: this call owns the pass and
+        // rewrites it below.
+    }
+    const bootMinute = computeBootMinute();
+    if (bootMinute !== null &&
+        recorded !== null &&
+        Number.isFinite(recorded) &&
+        Math.abs(recorded - bootMinute) <= 1) {
+        return false;
+    }
+    try {
+        fs.mkdirSync(getRuntimeHome(''), { recursive: true });
+        fs.writeFileSync(marker, String(bootMinute ?? ''), { mode: 0o600 });
+    }
+    catch {
+        // A pass that cannot be recorded runs again next time; the probe is cheap
+        // and the cleanup is not something to skip over a filesystem error.
+    }
+    return true;
+}
+/**
+ * The migration guard both entry points await before they do any work.
+ *
+ * Split by cost, not by entry point: the PID-file fast path is one read and runs
+ * on every command and every MCP server start, so a bridge that left its PID
+ * file behind is stopped even by `--version`; the port window is swept once per
+ * boot, which covers the orphan the PID file cannot name.
+ *
+ * Never throws, and never writes to stdout — the CLI's result and the MCP
+ * transport both own that stream, and a migration convenience must not be able
+ * to break either.
+ */
+export async function runLegacyMigrationGuard() {
+    if (!isMigrationActive()) {
+        return;
+    }
+    // Under `sudo`, the bridge belongs to the invoking user, not to root.
+    const home = getEffectiveHome();
+    await stopLegacyBridge({ home });
+    if (!claimBootScopedPass()) {
+        return;
+    }
+    await probeAndStopLegacyBridges(legacyCandidatePorts(), { home });
+    notifyLegacyPackageInstalled();
+}
+//# sourceMappingURL=legacyBridgeCleanup.js.map