@mearl/setup 2.8.0 → 2.8.2

package/README.md

@@ -5,6 +5,7 @@ Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全
 ```bash
 npx @mearl/setup [install] [--local] [--cloud|--qoder-cloud] [--mcp] [--yes]
 npx @mearl/setup <update|uninstall> [--local] [--cloud|--qoder-cloud] [--mcp] [--yes]
+npx @mearl/setup extension [--force] [--yes]
 ```
 
 配置 AgentBay API Key 时只需执行一次下面的命令，然后在隐藏输入提示中粘贴 Key。
@@ -44,6 +45,42 @@ npx @mearl/setup agentbay
   可用 `--skip-skill` 跳过。
 - 卸载一个环境但另一个仍依赖全局 mearl skill 时会保留 skill。
 - `--mcp` 的客户端配置和清理由 `@mearl/mcp-server` 自己的命令完成。
+- 默认的 `install` / `update` 不处理浏览器扩展。`extension` 是独立命令：从
+  `https://mearl.alibaba-inc.com/` 识别并下载最新的 `mearl-chrome-v*.zip`，原子解压到
+  `~/.mearl/chrome-extension`。首次安装通过浏览器级 CDP 的 `Extensions.loadUnpacked`
+  加载；后续更新由 `mearl check --local --json` 确认当前扩展仍来自 setup 管理目录后，直接替换
+  文件并通过 Native Host 触发扩展 reload。固定目录和 manifest 中的 `key` 保证扩展 ID
+  与浏览器存储保持稳定。
+- 下载前会通过 CDP 检查同 ID 插件的来源。未安装，或来源为固定目录中的 `UNPACKED`
+  插件时可继续；Chrome 商店、企业策略或其他本地目录安装的版本默认保持不变。只有显式
+  传入 `--force` 才会接管并替换这些版本。
+
+## 安装或更新浏览器扩展
+
+```bash
+npx @mearl/setup extension
+```
+
+首次安装、旧版 setup 扩展首次迁移，或 Native Host reload 不可用时才需要 CDP。如果
+Chrome 尚未开放 CDP，交互命令会提示打开
+`chrome://inspect/#remote-debugging`、启用远程调试并允许连接，然后等待安装完成。无 TTY
+环境使用 `npx @mearl/setup extension --yes`；它只尝试一次。无法确认 setup 管理来源且
+CDP 不可用时不会下载或修改插件目录，打开 CDP 后重新执行同一命令即可。
+
+该命令每次都读取下载页上的最新插件版本，不要求与 setup、CLI 或 Native Host 同版本。
+CDP 来源检查和 `Extensions.loadUnpacked` 复用同一条连接，避免一次安装重复请求授权。
+安装成功后目录内会保存 setup 管理标记；`mearl check --local --json` 同时从当前运行扩展读取该
+标记，只有两侧路径一致时才允许无 CDP 更新。如果用户后来改装 Chrome 商店版本，运行中
+的扩展不会返回 setup 标记，命令会重新通过 CDP 检查来源，并在未传 `--force` 时保持商店
+版本不变。
+
+setup 管理的扩展会读取远端 `config.json` 检查新版本，但不会静默更新。发现更高版本后，
+DevTools 面板的设置按钮会显示红点，快捷设置中提供“立即更新”和对应版本的“更新日志”。
+只有用户点击“立即更新”后，Native Host 才会重新校验远端版本、setup 管理标记、下载地址、
+可选的 SHA256 和压缩包 manifest，再原子替换目录并 reload。该入口不会回退到 CDP；商店版、
+企业策略版和其他本地目录版本不会进入 setup 更新链路。对于 Chrome 自身管理并已下载完成的
+更新，扩展只被动监听 `runtime.onUpdateAvailable`，沿用相同的更新提示并由用户点击 reload；不会
+调用 `runtime.requestUpdateCheck()` 主动检查。
 
 ## 跟随浏览器扩展自动更新
 
@@ -87,6 +124,9 @@ npx @mearl/setup --local --cloud
 # 自动更新当前 PATH 中检测到的全部 Mearl 环境
 npx @mearl/setup update
 
+# 独立安装或更新到最新浏览器扩展
+npx @mearl/setup extension
+
 # 只卸载本地环境
 npx @mearl/setup uninstall --local
 

package/dist/browserExtension.d.ts

@@ -0,0 +1,78 @@
+export declare const MEARL_EXTENSION_DOWNLOAD_PAGE = "https://mearl.alibaba-inc.com/";
+export declare const MEARL_EXTENSION_REMOTE_CONFIG_URL = "https://mearl.alibaba-inc.com/config.json";
+export declare const MEARL_EXTENSION_DIRECTORY_NAME = "chrome-extension";
+export declare const MEARL_EXTENSION_ID = "aoehhjnofngknnjefamjbplchbolghkm";
+export declare const MEARL_EXTENSION_SETUP_MARKER = ".mearl-setup.json";
+export interface BrowserExtensionRelease {
+    archiveUrl: string;
+    sha256?: string;
+    version: string;
+}
+export interface BrowserExtensionInstallOptions {
+    force?: boolean;
+    targetDirectory?: string;
+    chromeUserDataDirectory?: string;
+    waitForCdpMs?: number;
+    writeLine?: (line: string) => void;
+    release?: BrowserExtensionRelease;
+}
+export interface SetupManagedBrowserExtensionUpdateOptions {
+    release: BrowserExtensionRelease;
+    targetDirectory: string;
+}
+export interface SetupManagedBrowserExtensionUpdateResult extends BrowserExtensionRelease {
+    path: string;
+}
+export interface BrowserExtensionInstallResult {
+    activation?: 'cdp' | 'native-host';
+    extensionId?: string;
+    filesUpdated?: boolean;
+    loaded: boolean;
+    path: string;
+    version: string;
+    archiveUrl: string;
+    cdpError?: string;
+}
+export interface BrowserExtensionDependencies {
+    connectCdp?: typeof connectBrowserExtensionViaCdp;
+    extractArchive?: (archivePath: string, destination: string) => Promise<void>;
+    fetch?: typeof fetch;
+    inspectInstalled?: typeof inspectSetupManagedExtension;
+    inspectInstallation?: typeof inspectMearlExtensionViaCdp;
+    loadUnpacked?: typeof loadUnpackedViaCdp;
+    reloadInstalled?: typeof reloadInstalledExtension;
+    sleep?: (milliseconds: number) => Promise<void>;
+}
+export interface InstalledBrowserExtension {
+    id: string;
+    location: string;
+    name: string;
+    path: string;
+    version: string;
+}
+export declare class BrowserExtensionConflictError extends Error {
+    readonly installed: InstalledBrowserExtension;
+    constructor(installed: InstalledBrowserExtension);
+}
+export declare function resolveChromeUserDataDirectory(platform?: NodeJS.Platform, home?: string, env?: NodeJS.ProcessEnv): string;
+export declare function resolveMearlExtensionDirectory(home?: string): string;
+export declare function findLatestExtensionVersion(html: string): string | null;
+export declare function extensionArchiveUrl(version: string): string;
+export declare function fetchBrowserExtensionRelease(fetchImpl?: typeof fetch): Promise<BrowserExtensionRelease>;
+interface BrowserExtensionCdpSession {
+    close(): void;
+    inspectInstallation(): Promise<InstalledBrowserExtension | null>;
+    loadUnpacked(extensionDirectory: string): Promise<{
+        extensionId: string;
+    }>;
+}
+declare function connectBrowserExtensionViaCdp(chromeUserDataDirectory?: string): Promise<BrowserExtensionCdpSession>;
+export declare function loadUnpackedViaCdp(extensionDirectory: string, chromeUserDataDirectory?: string): Promise<{
+    extensionId: string;
+}>;
+export declare function inspectMearlExtensionViaCdp(chromeUserDataDirectory?: string): Promise<InstalledBrowserExtension | null>;
+declare function inspectSetupManagedExtension(targetDirectory: string): Promise<string[]>;
+declare function reloadInstalledExtension(browserIds: string[]): Promise<void>;
+export declare function updateSetupManagedBrowserExtensionFiles(options: SetupManagedBrowserExtensionUpdateOptions, dependencies?: Pick<BrowserExtensionDependencies, 'extractArchive' | 'fetch'>): Promise<SetupManagedBrowserExtensionUpdateResult>;
+export declare function installMearlBrowserExtension(options?: BrowserExtensionInstallOptions, dependencies?: BrowserExtensionDependencies): Promise<BrowserExtensionInstallResult>;
+export {};

package/dist/browserExtension.js

@@ -0,0 +1,612 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { runUnifiedCheck } from '@mearl/client/check';
+import { CLIENT_VERSION, invoke as invokeLocalMearl } from '@mearl/client/local';
+import extractZip from 'extract-zip';
+import WebSocket from 'ws';
+import { compareMearlReleaseVersions, isMearlReleaseVersion } from './version.js';
+export const MEARL_EXTENSION_DOWNLOAD_PAGE = 'https://mearl.alibaba-inc.com/';
+export const MEARL_EXTENSION_REMOTE_CONFIG_URL = `${MEARL_EXTENSION_DOWNLOAD_PAGE}config.json`;
+export const MEARL_EXTENSION_DIRECTORY_NAME = 'chrome-extension';
+export const MEARL_EXTENSION_ID = 'aoehhjnofngknnjefamjbplchbolghkm';
+export const MEARL_EXTENSION_SETUP_MARKER = '.mearl-setup.json';
+const ARCHIVE_PATTERN = /mearl-chrome-v(\d+\.\d+\.\d+(?:-beta\.\d+)?)\.zip/g;
+const MAX_ARCHIVE_BYTES = 64 * 1024 * 1024;
+const SHA256_PATTERN = /^[a-f\d]{64}$/i;
+export class BrowserExtensionConflictError extends Error {
+    installed;
+    constructor(installed) {
+        super(`Mearl extension ${installed.id} is already installed from ${installed.location} at ${installed.path || '(managed location)'}. Re-run with --force to replace it.`);
+        this.installed = installed;
+        this.name = 'BrowserExtensionConflictError';
+    }
+}
+export function resolveChromeUserDataDirectory(platform = process.platform, home = os.homedir(), env = process.env) {
+    if (platform === 'darwin') {
+        return path.join(home, 'Library', 'Application Support', 'Google', 'Chrome');
+    }
+    if (platform === 'win32') {
+        return path.join(env.LOCALAPPDATA ?? home, 'Google', 'Chrome', 'User Data');
+    }
+    return path.join(home, '.config', 'google-chrome');
+}
+export function resolveMearlExtensionDirectory(home = os.homedir()) {
+    return path.join(home, '.mearl', MEARL_EXTENSION_DIRECTORY_NAME);
+}
+export function findLatestExtensionVersion(html) {
+    const versions = Array.from(html.matchAll(ARCHIVE_PATTERN), match => match[1]).filter(isMearlReleaseVersion);
+    return versions.sort(compareMearlReleaseVersions).at(-1) ?? null;
+}
+export function extensionArchiveUrl(version) {
+    if (!isMearlReleaseVersion(version)) {
+        throw new Error(`Invalid Mearl browser extension version: ${version}`);
+    }
+    return new URL(`mearl-chrome-v${version}.zip`, MEARL_EXTENSION_DOWNLOAD_PAGE).toString();
+}
+function validateExtensionRelease(release) {
+    if (!isMearlReleaseVersion(release.version)) {
+        throw new Error('Remote extension config has an invalid latestVersion');
+    }
+    const expectedArchiveUrl = extensionArchiveUrl(release.version);
+    let archiveUrl;
+    try {
+        archiveUrl = new URL(release.archiveUrl).toString();
+    }
+    catch {
+        throw new Error('Remote extension config has an invalid downloadUrl');
+    }
+    if (archiveUrl !== expectedArchiveUrl) {
+        throw new Error('Remote extension downloadUrl does not match latestVersion');
+    }
+    if (release.sha256 !== undefined && !SHA256_PATTERN.test(release.sha256)) {
+        throw new Error('Remote extension config has an invalid downloadSha256');
+    }
+    return {
+        archiveUrl,
+        ...(release.sha256 ? { sha256: release.sha256.toLowerCase() } : {}),
+        version: release.version,
+    };
+}
+export async function fetchBrowserExtensionRelease(fetchImpl = fetch) {
+    const response = await fetchImpl(MEARL_EXTENSION_REMOTE_CONFIG_URL, { cache: 'no-store' });
+    if (!response.ok) {
+        throw new Error(`Extension config returned HTTP ${response.status}`);
+    }
+    const config = (await response.json());
+    return validateExtensionRelease({
+        archiveUrl: typeof config.downloadUrl === 'string' ? config.downloadUrl : '',
+        ...(typeof config.downloadSha256 === 'string' ? { sha256: config.downloadSha256 } : {}),
+        version: typeof config.latestVersion === 'string' ? config.latestVersion : '',
+    });
+}
+async function resolveExtensionArchive(fetchImpl) {
+    const response = await fetchImpl(MEARL_EXTENSION_DOWNLOAD_PAGE, { redirect: 'follow' });
+    if (!response.ok) {
+        throw new Error(`Extension release page returned HTTP ${response.status}`);
+    }
+    const version = findLatestExtensionVersion(await response.text());
+    if (!version)
+        throw new Error('No Mearl browser extension archive was found on the release page');
+    return { version, archiveUrl: extensionArchiveUrl(version) };
+}
+function readDevToolsActivePort(userDataDirectory) {
+    try {
+        const content = fs
+            .readFileSync(path.join(userDataDirectory, 'DevToolsActivePort'), 'utf8')
+            .trim();
+        const [portValue, browserWsPath = '/devtools/browser'] = content
+            .split(/\r?\n/)
+            .map(value => value.trim());
+        const port = Number(portValue);
+        if (!Number.isInteger(port) || port <= 0 || port > 65_535)
+            return null;
+        if (!browserWsPath.startsWith('/'))
+            return null;
+        return { port, browserWsPath };
+    }
+    catch {
+        return null;
+    }
+}
+function rawDataToString(data) {
+    if (Array.isArray(data))
+        return Buffer.concat(data).toString('utf8');
+    if (Buffer.isBuffer(data))
+        return data.toString('utf8');
+    return Buffer.from(data).toString('utf8');
+}
+class CdpConnection {
+    socket;
+    closed = false;
+    nextId = 1;
+    pending = new Map();
+    constructor(socket) {
+        this.socket = socket;
+        socket.on('message', data => this.handleMessage(data));
+        socket.on('close', () => this.close(new Error('CDP WebSocket closed before responding')));
+        socket.on('error', error => this.close(error));
+    }
+    static connect(endpoint) {
+        return new Promise((resolve, reject) => {
+            const socket = new WebSocket(endpoint, {
+                handshakeTimeout: 5_000,
+                maxPayload: 8 * 1024 * 1024,
+                perMessageDeflate: false,
+            });
+            let settled = false;
+            const finish = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (error) {
+                    socket.terminate();
+                    reject(error);
+                }
+                else {
+                    resolve(new CdpConnection(socket));
+                }
+            };
+            socket.once('open', () => finish());
+            socket.once('error', error => finish(error));
+            socket.once('unexpected-response', (_request, response) => {
+                response.resume();
+                finish(new Error(`CDP WebSocket returned HTTP ${response.statusCode ?? 0}`));
+            });
+        });
+    }
+    send(method, params = {}, sessionId, timeoutMs = 10_000) {
+        return new Promise((resolve, reject) => {
+            const id = this.nextId++;
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`CDP command timed out: ${method}`));
+            }, timeoutMs);
+            this.pending.set(id, { reject, resolve, timer });
+            this.socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }), error => {
+                if (!error)
+                    return;
+                const pending = this.pending.get(id);
+                if (!pending)
+                    return;
+                clearTimeout(pending.timer);
+                this.pending.delete(id);
+                pending.reject(error);
+            });
+        });
+    }
+    close(error = new Error('CDP connection closed')) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+        this.socket.terminate();
+    }
+    handleMessage(data) {
+        try {
+            const message = JSON.parse(rawDataToString(data));
+            if (message.id === undefined)
+                return;
+            const pending = this.pending.get(message.id);
+            if (!pending)
+                return;
+            clearTimeout(pending.timer);
+            this.pending.delete(message.id);
+            if (message.error) {
+                pending.reject(new Error(message.error.message ?? 'CDP command failed'));
+            }
+            else {
+                pending.resolve(message.result ?? {});
+            }
+        }
+        catch {
+            // Ignore unrelated malformed protocol events and let command timeouts report failure.
+        }
+    }
+}
+function sameExtensionPath(left, right) {
+    const normalizedLeft = path.normalize(path.resolve(left));
+    const normalizedRight = path.normalize(path.resolve(right));
+    return process.platform === 'win32'
+        ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+        : normalizedLeft === normalizedRight;
+}
+function isSetupManagedInstallation(installed, targetDirectory) {
+    return installed.location === 'UNPACKED' && sameExtensionPath(installed.path, targetDirectory);
+}
+function setupMarkerPath(directory) {
+    return path.join(directory, MEARL_EXTENSION_SETUP_MARKER);
+}
+function hasSetupMarker(targetDirectory) {
+    try {
+        const marker = JSON.parse(fs.readFileSync(setupMarkerPath(targetDirectory), 'utf8'));
+        return (marker.schemaVersion === 1 &&
+            marker.extensionId === MEARL_EXTENSION_ID &&
+            typeof marker.path === 'string' &&
+            sameExtensionPath(marker.path, targetDirectory));
+    }
+    catch {
+        return false;
+    }
+}
+async function writeSetupMarker(directory, targetDirectory) {
+    const marker = {
+        extensionId: MEARL_EXTENSION_ID,
+        path: path.resolve(targetDirectory),
+        schemaVersion: 1,
+    };
+    await fs.promises.writeFile(setupMarkerPath(directory), `${JSON.stringify(marker, null, 2)}\n`, {
+        mode: 0o600,
+    });
+}
+function browserCdpEndpoint(chromeUserDataDirectory) {
+    const activePort = readDevToolsActivePort(chromeUserDataDirectory);
+    if (!activePort)
+        throw new Error('Chrome remote debugging is not enabled');
+    return `ws://127.0.0.1:${activePort.port}${activePort.browserWsPath}`;
+}
+async function inspectInstallationWithConnection(connection) {
+    const target = await connection.send('Target.createTarget', {
+        background: true,
+        url: 'chrome://extensions-internals',
+    });
+    try {
+        const attached = await connection.send('Target.attachToTarget', {
+            flatten: true,
+            targetId: target.targetId,
+        });
+        const evaluated = await connection.send('Runtime.evaluate', {
+            awaitPromise: true,
+            expression: "document.readyState === 'complete' ? document.body.innerText : new Promise(resolve => addEventListener('load', () => resolve(document.body.innerText), {once:true}))",
+            returnByValue: true,
+        }, attached.sessionId);
+        const text = evaluated.result?.value;
+        if (typeof text !== 'string') {
+            throw new Error('chrome://extensions-internals did not return extension inventory');
+        }
+        const inventory = JSON.parse(text);
+        const installed = inventory.find(extension => extension.id === MEARL_EXTENSION_ID);
+        if (!installed)
+            return null;
+        if (typeof installed.location !== 'string' ||
+            typeof installed.name !== 'string' ||
+            typeof installed.path !== 'string' ||
+            typeof installed.version !== 'string') {
+            throw new Error('Chrome returned incomplete Mearl extension metadata');
+        }
+        return {
+            id: MEARL_EXTENSION_ID,
+            location: installed.location,
+            name: installed.name,
+            path: installed.path,
+            version: installed.version,
+        };
+    }
+    finally {
+        if (typeof target.targetId === 'string') {
+            await connection.send('Target.closeTarget', { targetId: target.targetId }).catch(() => { });
+        }
+    }
+}
+async function loadUnpackedWithConnection(connection, extensionDirectory) {
+    const loaded = await connection.send('Extensions.loadUnpacked', {
+        path: path.resolve(extensionDirectory),
+    });
+    if (loaded.id !== MEARL_EXTENSION_ID) {
+        throw new Error(`Extensions.loadUnpacked returned unexpected extension ID: ${String(loaded.id)}`);
+    }
+    const inventory = await connection.send('Extensions.getExtensions');
+    const extension = Array.isArray(inventory.extensions)
+        ? inventory.extensions.find(candidate => candidate?.id === loaded.id)
+        : null;
+    if (!extension?.enabled) {
+        throw new Error('Chrome loaded the extension but did not report it as enabled');
+    }
+    return { extensionId: loaded.id };
+}
+async function connectBrowserExtensionViaCdp(chromeUserDataDirectory = resolveChromeUserDataDirectory()) {
+    const connection = await CdpConnection.connect(browserCdpEndpoint(chromeUserDataDirectory));
+    return {
+        close: () => connection.close(),
+        inspectInstallation: () => inspectInstallationWithConnection(connection),
+        loadUnpacked: extensionDirectory => loadUnpackedWithConnection(connection, extensionDirectory),
+    };
+}
+export async function loadUnpackedViaCdp(extensionDirectory, chromeUserDataDirectory = resolveChromeUserDataDirectory()) {
+    const connection = await CdpConnection.connect(browserCdpEndpoint(chromeUserDataDirectory));
+    try {
+        return await loadUnpackedWithConnection(connection, extensionDirectory);
+    }
+    finally {
+        connection.close();
+    }
+}
+export async function inspectMearlExtensionViaCdp(chromeUserDataDirectory = resolveChromeUserDataDirectory()) {
+    const connection = await CdpConnection.connect(browserCdpEndpoint(chromeUserDataDirectory));
+    try {
+        return await inspectInstallationWithConnection(connection);
+    }
+    finally {
+        connection.close();
+    }
+}
+async function inspectSetupManagedExtension(targetDirectory) {
+    const result = await runUnifiedCheck({ clientVersion: CLIENT_VERSION, json: true, local: true, timeoutSec: 5 }, { writeJson: () => { } });
+    const matches = result.browsers
+        .filter(browser => browser.status === 'connected' &&
+        browser.transport === 'extension' &&
+        browser.extensionInstallation?.extensionId === MEARL_EXTENSION_ID &&
+        typeof browser.extensionInstallation.setupManagedPath === 'string' &&
+        sameExtensionPath(browser.extensionInstallation.setupManagedPath, targetDirectory))
+        .map(browser => browser.browserId);
+    return matches;
+}
+async function reloadInstalledExtension(browserIds) {
+    if (browserIds.length === 0)
+        throw new Error('No setup-managed Mearl extension was found');
+    const failures = [];
+    let reloaded = 0;
+    for (const browserId of browserIds) {
+        try {
+            await invokeLocalMearl('__extension_reload', {}, {
+                browser: browserId,
+                timeoutSec: 5,
+            });
+            reloaded += 1;
+        }
+        catch (error) {
+            failures.push(error instanceof Error ? error.message : String(error));
+        }
+    }
+    if (reloaded === 0) {
+        throw new Error(`Failed to reload the connected extension: ${failures.join('; ')}`);
+    }
+}
+async function replaceDirectory(stagingDirectory, targetDirectory) {
+    const backupDirectory = `${targetDirectory}.backup-${randomUUID()}`;
+    const targetExists = fs.existsSync(targetDirectory);
+    try {
+        if (targetExists)
+            await fs.promises.rename(targetDirectory, backupDirectory);
+        await fs.promises.rename(stagingDirectory, targetDirectory);
+    }
+    catch (error) {
+        if (!fs.existsSync(targetDirectory) && fs.existsSync(backupDirectory)) {
+            await fs.promises.rename(backupDirectory, targetDirectory);
+        }
+        throw error;
+    }
+    if (targetExists) {
+        await fs.promises.rm(backupDirectory, { force: true, recursive: true });
+    }
+}
+function readExtensionManifest(directory) {
+    const manifestPath = path.join(directory, 'manifest.json');
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`Downloaded extension has no valid manifest.json: ${error instanceof Error ? error.message : error}`, { cause: error });
+    }
+    if (parsed.manifest_version !== 3 ||
+        typeof parsed.name !== 'string' ||
+        typeof parsed.key !== 'string' ||
+        parsed.key.length === 0) {
+        throw new Error('Downloaded archive is not a valid Manifest V3 extension');
+    }
+    if (!isMearlReleaseVersion(parsed.version)) {
+        throw new Error('Downloaded extension manifest has an invalid version');
+    }
+    return parsed;
+}
+async function downloadAndReplaceExtension(releaseInput, targetDirectory, fetchImpl, extractArchive) {
+    const release = validateExtensionRelease(releaseInput);
+    const parentDirectory = path.dirname(targetDirectory);
+    const stagingDirectory = `${targetDirectory}.staging-${randomUUID()}`;
+    const archivePath = path.join(parentDirectory, `.mearl-extension-${randomUUID()}.zip`);
+    await fs.promises.mkdir(parentDirectory, { recursive: true });
+    try {
+        const response = await fetchImpl(release.archiveUrl, { redirect: 'follow' });
+        if (!response.ok) {
+            throw new Error(`Extension archive returned HTTP ${response.status}: ${release.archiveUrl}`);
+        }
+        const contentLength = Number(response.headers.get('content-length') ?? 0);
+        if (contentLength > MAX_ARCHIVE_BYTES) {
+            throw new Error(`Extension archive exceeds ${MAX_ARCHIVE_BYTES} bytes`);
+        }
+        const archive = Buffer.from(await response.arrayBuffer());
+        if (archive.length === 0 || archive.length > MAX_ARCHIVE_BYTES) {
+            throw new Error('Extension archive is empty or too large');
+        }
+        if (release.sha256) {
+            const actualSha256 = createHash('sha256').update(archive).digest('hex');
+            if (actualSha256 !== release.sha256) {
+                throw new Error('Extension archive SHA256 does not match remote config');
+            }
+        }
+        await fs.promises.writeFile(archivePath, archive, { mode: 0o600 });
+        await fs.promises.mkdir(stagingDirectory, { recursive: true });
+        await extractArchive(archivePath, stagingDirectory);
+        const manifest = readExtensionManifest(stagingDirectory);
+        if (manifest.version !== release.version) {
+            throw new Error(`Extension archive version ${String(manifest.version)} does not match ${release.version}`);
+        }
+        await writeSetupMarker(stagingDirectory, targetDirectory);
+        await replaceDirectory(stagingDirectory, targetDirectory);
+        return release;
+    }
+    finally {
+        await fs.promises.rm(archivePath, { force: true });
+        await fs.promises.rm(stagingDirectory, { force: true, recursive: true });
+    }
+}
+export async function updateSetupManagedBrowserExtensionFiles(options, dependencies = {}) {
+    const targetDirectory = path.resolve(options.targetDirectory);
+    if (!hasSetupMarker(targetDirectory)) {
+        throw new Error('The running extension is not managed by Mearl setup');
+    }
+    const fetchImpl = dependencies.fetch ?? fetch;
+    const extractArchive = dependencies.extractArchive ??
+        ((archivePath, destination) => extractZip(archivePath, { dir: destination }));
+    const release = await downloadAndReplaceExtension(options.release, targetDirectory, fetchImpl, extractArchive);
+    return { ...release, path: targetDirectory };
+}
+export async function installMearlBrowserExtension(options = {}, dependencies = {}) {
+    const connectCdp = dependencies.connectCdp ?? connectBrowserExtensionViaCdp;
+    const fetchImpl = dependencies.fetch ?? fetch;
+    const extractArchive = dependencies.extractArchive ??
+        ((archivePath, destination) => extractZip(archivePath, { dir: destination }));
+    const loadUnpacked = dependencies.loadUnpacked ?? loadUnpackedViaCdp;
+    const inspectInstallation = dependencies.inspectInstallation ?? inspectMearlExtensionViaCdp;
+    const inspectInstalled = dependencies.inspectInstalled ?? inspectSetupManagedExtension;
+    const reloadInstalled = dependencies.reloadInstalled ?? reloadInstalledExtension;
+    const sleep = dependencies.sleep ??
+        (milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds)));
+    const writeLine = options.writeLine ?? (line => console.error(line));
+    const targetDirectory = path.resolve(options.targetDirectory ?? resolveMearlExtensionDirectory());
+    const release = options.release
+        ? validateExtensionRelease(options.release)
+        : await resolveExtensionArchive(fetchImpl);
+    const chromeUserDataDirectory = options.chromeUserDataDirectory ?? resolveChromeUserDataDirectory();
+    const waitForCdpMs = Math.max(0, options.waitForCdpMs ?? 0);
+    const useSharedCdpSession = !dependencies.inspectInstallation && !dependencies.loadUnpacked;
+    let setupManagedBrowserIds = [];
+    if (hasSetupMarker(targetDirectory)) {
+        try {
+            setupManagedBrowserIds = await inspectInstalled(targetDirectory);
+        }
+        catch {
+            // A missing Native Host connection cannot prove ownership; CDP performs the safe fallback.
+        }
+    }
+    const setupManagedAtStart = setupManagedBrowserIds.length > 0;
+    let cdpSession;
+    const inspectOnce = async () => {
+        if (!useSharedCdpSession)
+            return inspectInstallation(chromeUserDataDirectory);
+        const candidate = await connectCdp(chromeUserDataDirectory);
+        try {
+            const installed = await candidate.inspectInstallation();
+            cdpSession?.close();
+            cdpSession = candidate;
+            return installed;
+        }
+        catch (error) {
+            candidate.close();
+            throw error;
+        }
+    };
+    const waitForCdpInspection = async () => {
+        const deadline = Date.now() + waitForCdpMs;
+        let lastFailure;
+        let lastNoticeAt = 0;
+        do {
+            try {
+                const installed = await inspectOnce();
+                if (installed &&
+                    !isSetupManagedInstallation(installed, targetDirectory) &&
+                    !options.force) {
+                    throw new BrowserExtensionConflictError(installed);
+                }
+                return undefined;
+            }
+            catch (error) {
+                if (error instanceof BrowserExtensionConflictError)
+                    throw error;
+                const message = error instanceof Error ? error.message : String(error);
+                lastFailure = message;
+                if (waitForCdpMs === 0 || /Method not (?:available|found)|wasn't found/i.test(message)) {
+                    break;
+                }
+                if (lastNoticeAt === 0) {
+                    writeLine('Waiting for Chrome remote debugging before checking the installed extension...');
+                    writeLine('Open chrome://inspect/#remote-debugging, enable remote debugging, and approve the connection.');
+                    lastNoticeAt = Date.now();
+                }
+                else if (Date.now() - lastNoticeAt >= 15_000) {
+                    writeLine('Still waiting for Chrome remote debugging...');
+                    lastNoticeAt = Date.now();
+                }
+                await sleep(Math.min(1_000, Math.max(0, deadline - Date.now())));
+            }
+        } while (Date.now() < deadline);
+        return lastFailure;
+    };
+    try {
+        if (!setupManagedAtStart) {
+            const cdpError = await waitForCdpInspection();
+            if (cdpError) {
+                return {
+                    filesUpdated: false,
+                    loaded: false,
+                    path: targetDirectory,
+                    version: release.version,
+                    archiveUrl: release.archiveUrl,
+                    cdpError,
+                };
+            }
+        }
+        await downloadAndReplaceExtension(release, targetDirectory, fetchImpl, extractArchive);
+        if (setupManagedAtStart) {
+            try {
+                await reloadInstalled(setupManagedBrowserIds);
+                return {
+                    activation: 'native-host',
+                    extensionId: MEARL_EXTENSION_ID,
+                    filesUpdated: true,
+                    loaded: true,
+                    path: targetDirectory,
+                    version: release.version,
+                    archiveUrl: release.archiveUrl,
+                };
+            }
+            catch (reloadError) {
+                const cdpError = await waitForCdpInspection();
+                if (cdpError) {
+                    const reloadMessage = reloadError instanceof Error ? reloadError.message : String(reloadError);
+                    return {
+                        filesUpdated: true,
+                        loaded: false,
+                        path: targetDirectory,
+                        version: release.version,
+                        archiveUrl: release.archiveUrl,
+                        cdpError: `Native Host reload failed: ${reloadMessage}; CDP fallback failed: ${cdpError}`,
+                    };
+                }
+            }
+        }
+        try {
+            const loaded = cdpSession
+                ? await cdpSession.loadUnpacked(targetDirectory)
+                : await loadUnpacked(targetDirectory, chromeUserDataDirectory);
+            return {
+                activation: 'cdp',
+                extensionId: loaded.extensionId,
+                filesUpdated: true,
+                loaded: true,
+                path: targetDirectory,
+                version: release.version,
+                archiveUrl: release.archiveUrl,
+            };
+        }
+        catch (error) {
+            return {
+                filesUpdated: true,
+                loaded: false,
+                path: targetDirectory,
+                version: release.version,
+                archiveUrl: release.archiveUrl,
+                cdpError: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    finally {
+        cdpSession?.close();
+    }
+}

package/dist/cli.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin } from './agentBay.js';
+import { installMearlBrowserExtension } from './browserExtension.js';
 import { runMearlLifecycle, type MearlLifecycleOperation } from './lifecycle.js';
 import type { MearlProfile } from './profiles.js';
 export declare const SETUP_VERSION: string;
@@ -7,8 +8,9 @@ interface ParsedArgs {
     agentBayKeyFile?: string;
     agentBayReadStdin: boolean;
     cloudMode?: 'websocket' | 'qoder';
+    force?: boolean;
     help: boolean;
-    operation?: MearlLifecycleOperation | 'agentbay';
+    operation?: MearlLifecycleOperation | 'agentbay' | 'extension';
     profiles?: MearlProfile[];
     skipSkill: boolean;
     targetLine?: string;
@@ -20,6 +22,7 @@ export interface SetupCliDependencies {
     promptAgentBayKey?: typeof promptAgentBayApiKey;
     readAgentBayKeyFile?: typeof readAgentBayApiKeyFile;
     readAgentBayKeyStdin?: typeof readAgentBayApiKeyStdin;
+    installBrowserExtension?: typeof installMearlBrowserExtension;
     runLifecycle?: typeof runMearlLifecycle;
 }
 export declare function parseSetupArgs(argv: string[]): ParsedArgs;

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
 import { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin, } from './agentBay.js';
+import { installMearlBrowserExtension } from './browserExtension.js';
 import { runMearlLifecycle } from './lifecycle.js';
 import { isMearlReleaseLine } from './version.js';
 const require = createRequire(import.meta.url);
@@ -52,6 +53,21 @@ export function parseSetupArgs(argv) {
         }
         throw new Error('Usage: npx @mearl/setup agentbay [--stdin | --key-file <path>]. API keys are not accepted as command-line arguments.');
     }
+    if (operation === 'extension') {
+        const accepted = new Set(['--force', '--yes', '-y', '--non-interactive']);
+        const confirmationFlags = new Set(['--yes', '-y', '--non-interactive']);
+        const unknown = argv.slice(1).find(arg => !accepted.has(arg));
+        if (unknown)
+            throw new Error(`Unknown option: ${unknown}`);
+        return {
+            agentBayReadStdin: false,
+            help: false,
+            ...(argv.slice(1).includes('--force') ? { force: true } : {}),
+            operation,
+            skipSkill: false,
+            yes: argv.slice(1).some(arg => confirmationFlags.has(arg)),
+        };
+    }
     if (operation !== 'install' && operation !== 'update' && operation !== 'uninstall') {
         throw new Error(`Unknown operation: ${operation}`);
     }
@@ -118,12 +134,14 @@ function printHelp(toError = false) {
 Usage:
   npx @mearl/setup [install] [--local] [--cloud|--qoder-cloud] [--mcp] [--yes]
   npx @mearl/setup <update|uninstall> [--local] [--cloud|--qoder-cloud] [--mcp] [--yes]
+  npx @mearl/setup extension [--force] [--yes]
   npx @mearl/setup agentbay [--stdin | --key-file <path>]
 
 Behavior:
   install      Default command; defaults to --local when no environment is specified
   update       Auto-detects installed environments from the current PATH
   uninstall    Auto-detects installed environments and asks for confirmation
+  extension    Download the latest browser extension and install or reload it through CDP
   agentbay     Save or update AGENTBAY_KEY without changing other Mearl settings
 
 Options:
@@ -137,6 +155,7 @@ Options:
   --target-line <major.minor.x>
                Install the latest packages from one release line, such as 2.3.x
   --skip-skill Keep the independently managed Mearl Skill unchanged
+  --force      Replace an existing store, managed, or other local Mearl extension
   --yes, -y    Run without prompts and accept detected defaults
   --non-interactive
                Alias for --yes, intended for Agents and CI
@@ -151,6 +170,7 @@ Examples:
   npx @mearl/setup --cloud
   npx @mearl/setup --local --cloud
   npx @mearl/setup update
+  npx @mearl/setup extension
   npx @mearl/setup agentbay
   npx @mearl/setup --qoder-cloud --yes
   npx @mearl/setup update --local --target-line 2.3.x --skip-skill
@@ -203,6 +223,38 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
             return 1;
         }
     }
+    if (parsed.operation === 'extension') {
+        if (!interactiveTerminal && !parsed.yes) {
+            console.error('Non-interactive input detected. Re-run with --yes or --non-interactive.');
+            return 2;
+        }
+        try {
+            const result = await (dependencies.installBrowserExtension ?? installMearlBrowserExtension)({
+                force: parsed.force,
+                waitForCdpMs: interactiveTerminal && !parsed.yes ? 120_000 : 0,
+                writeLine: line => console.error(line),
+            });
+            if (result.loaded) {
+                console.error(result.activation === 'native-host'
+                    ? `Browser extension v${result.version} updated and reloaded without CDP.`
+                    : `Browser extension v${result.version} installed or reloaded through CDP.`);
+                console.error(`Extension ID: ${result.extensionId}`);
+                console.error(`Extension directory: ${result.path}`);
+                return 0;
+            }
+            console.error(result.filesUpdated
+                ? `Browser extension v${result.version} files were updated, but the extension was not reloaded.`
+                : `Browser extension v${result.version} was not installed.`);
+            if (result.cdpError)
+                console.error(`CDP installation pending: ${result.cdpError}`);
+            console.error('Open chrome://inspect/#remote-debugging, enable remote debugging, approve the connection, then rerun: npx @mearl/setup extension');
+            return 1;
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            return 1;
+        }
+    }
     if (!interactiveTerminal && !parsed.yes && parsed.operation !== 'update') {
         console.error('Non-interactive input detected. Re-run with --yes or --non-interactive.');
         return 2;

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { buildGlobalPackageCommand, detectGlobalPackage, resolveInvokingPackageManager, resolvePackageManagerInstallation, } from './packageManager.js';
 export { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin, } from './agentBay.js';
+export { BrowserExtensionConflictError, extensionArchiveUrl, fetchBrowserExtensionRelease, findLatestExtensionVersion, installMearlBrowserExtension, inspectMearlExtensionViaCdp, loadUnpackedViaCdp, MEARL_EXTENSION_DIRECTORY_NAME, MEARL_EXTENSION_DOWNLOAD_PAGE, MEARL_EXTENSION_ID, MEARL_EXTENSION_REMOTE_CONFIG_URL, resolveChromeUserDataDirectory, resolveMearlExtensionDirectory, updateSetupManagedBrowserExtensionFiles, } from './browserExtension.js';
+export type { BrowserExtensionDependencies, BrowserExtensionInstallOptions, BrowserExtensionInstallResult, BrowserExtensionRelease, InstalledBrowserExtension, SetupManagedBrowserExtensionUpdateOptions, SetupManagedBrowserExtensionUpdateResult, } from './browserExtension.js';
 export type { AgentBayConfigurationOptions, AgentBayConfigurationResult, AgentBaySecretInput, AgentBaySecretOutput, } from './agentBay.js';
 export type { DetectedGlobalPackage, GlobalPackageCommand, GlobalPackageManager, PackageManagerInstallation, PackageOperation, PackageDetectionOptions, } from './packageManager.js';
 export { runMearlLifecycle } from './lifecycle.js';
@@ -7,6 +9,6 @@ export type { MearlLifecycleDependencies, MearlLifecycleOperation, MearlLifecycl
 export { MEARL_PROFILES, detectMearlProfiles } from './profiles.js';
 export type { DetectedMearlProfiles, MearlProfile, MearlProfileConfig } from './profiles.js';
 export { MEARL_NATIVE_HOST_NAMES, resolveNativeHostDirectory, uninstallNativeHostArtifacts, } from './nativeHost.js';
-export { compareMearlReleaseLines, isMearlReleaseLine, isMearlReleaseVersion, isMearlReleaseVersionInLine, mearlReleaseLineForVersion, parseMearlReleaseLine, parseMearlReleaseVersion, } from './version.js';
+export { compareMearlReleaseLines, compareMearlReleaseVersions, isMearlReleaseLine, isMearlReleaseVersion, isMearlReleaseVersionInLine, mearlReleaseLineForVersion, parseMearlReleaseLine, parseMearlReleaseVersion, } from './version.js';
 export type { MearlReleaseLine, MearlReleaseVersion } from './version.js';
 export type { NativeHostCleanupDependencies, NativeHostCleanupOptions, NativeHostIntegrationMode, } from './nativeHost.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 export { buildGlobalPackageCommand, detectGlobalPackage, resolveInvokingPackageManager, resolvePackageManagerInstallation, } from './packageManager.js';
 export { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin, } from './agentBay.js';
+export { BrowserExtensionConflictError, extensionArchiveUrl, fetchBrowserExtensionRelease, findLatestExtensionVersion, installMearlBrowserExtension, inspectMearlExtensionViaCdp, loadUnpackedViaCdp, MEARL_EXTENSION_DIRECTORY_NAME, MEARL_EXTENSION_DOWNLOAD_PAGE, MEARL_EXTENSION_ID, MEARL_EXTENSION_REMOTE_CONFIG_URL, resolveChromeUserDataDirectory, resolveMearlExtensionDirectory, updateSetupManagedBrowserExtensionFiles, } from './browserExtension.js';
 export { runMearlLifecycle } from './lifecycle.js';
 export { MEARL_PROFILES, detectMearlProfiles } from './profiles.js';
 export { MEARL_NATIVE_HOST_NAMES, resolveNativeHostDirectory, uninstallNativeHostArtifacts, } from './nativeHost.js';
-export { compareMearlReleaseLines, isMearlReleaseLine, isMearlReleaseVersion, isMearlReleaseVersionInLine, mearlReleaseLineForVersion, parseMearlReleaseLine, parseMearlReleaseVersion, } from './version.js';
+export { compareMearlReleaseLines, compareMearlReleaseVersions, isMearlReleaseLine, isMearlReleaseVersion, isMearlReleaseVersionInLine, mearlReleaseLineForVersion, parseMearlReleaseLine, parseMearlReleaseVersion, } from './version.js';

package/dist/version.d.ts

@@ -19,3 +19,4 @@ export declare function isMearlReleaseLine(value: unknown): value is string;
 export declare function mearlReleaseLineForVersion(version: string): string;
 export declare function isMearlReleaseVersionInLine(version: string, releaseLine: string): boolean;
 export declare function compareMearlReleaseLines(leftVersion: string, rightVersion: string): -1 | 0 | 1;
+export declare function compareMearlReleaseVersions(leftVersion: string, rightVersion: string): -1 | 0 | 1;

package/dist/version.js

@@ -75,3 +75,25 @@ export function compareMearlReleaseLines(leftVersion, rightVersion) {
     }
     return 0;
 }
+export function compareMearlReleaseVersions(leftVersion, rightVersion) {
+    const left = parseMearlReleaseVersion(leftVersion);
+    const right = parseMearlReleaseVersion(rightVersion);
+    if (!left || !right) {
+        throw new Error('Mearl release comparison requires valid release versions');
+    }
+    for (const key of ['major', 'minor', 'patch']) {
+        if (left[key] < right[key])
+            return -1;
+        if (left[key] > right[key])
+            return 1;
+    }
+    if (left.channel !== right.channel)
+        return left.channel === 'stable' ? 1 : -1;
+    const leftBeta = left.beta ?? 0;
+    const rightBeta = right.beta ?? 0;
+    if (leftBeta < rightBeta)
+        return -1;
+    if (leftBeta > rightBeta)
+        return 1;
+    return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "2.8.0",
+  "version": "2.8.2",
   "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",
@@ -33,6 +33,10 @@
     "./version": {
       "types": "./dist/version.d.ts",
       "import": "./dist/version.js"
+    },
+    "./browser-extension": {
+      "types": "./dist/browserExtension.d.ts",
+      "import": "./dist/browserExtension.js"
     }
   },
   "bin": {
@@ -51,11 +55,20 @@
     "uninstall"
   ],
   "license": "ISC",
+  "engines": {
+    "node": ">=18"
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
   },
+  "dependencies": {
+    "extract-zip": "^2.0.1",
+    "ws": "^8.18.3",
+    "@mearl/client": "2.8.2"
+  },
   "devDependencies": {
     "@types/node": "^24.9.1",
+    "@types/ws": "^8.18.1",
     "typescript": "^5.8.3"
   },
   "scripts": {