@mearl/setup 2.8.0 → 2.8.1

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,28 @@ 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` 完成首次
+  安装或后续重载。固定目录和 manifest 中的 `key` 保证扩展 ID 与浏览器存储保持稳定。
+- 下载前会通过 CDP 检查同 ID 插件的来源。未安装，或来源为固定目录中的 `UNPACKED`
+  插件时可继续；Chrome 商店、企业策略或其他本地目录安装的版本默认保持不变。只有显式
+  传入 `--force` 才会接管并替换这些版本。
+
+## 安装或更新浏览器扩展
+
+```bash
+npx @mearl/setup extension
+```
+
+如果 Chrome 尚未开放 CDP，交互命令会提示打开
+`chrome://inspect/#remote-debugging`、启用远程调试并允许连接，然后等待安装完成。无 TTY
+环境使用 `npx @mearl/setup extension --yes`；它只尝试一次。CDP 不可用时不会下载或修改
+插件目录，打开 CDP 后重新执行同一命令即可。
+
+该命令每次都读取下载页上的最新插件版本，不要求与 setup、CLI 或 Native Host 同版本。
+已经从固定目录安装过时，新版本会先替换目录，再对同一路径调用
+`Extensions.loadUnpacked`，Chrome 会重载现有 unpacked 扩展。
 
 ## 跟随浏览器扩展自动更新
 
@@ -87,6 +110,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,45 @@
+export declare const MEARL_EXTENSION_DOWNLOAD_PAGE = "https://mearl.alibaba-inc.com/";
+export declare const MEARL_EXTENSION_DIRECTORY_NAME = "chrome-extension";
+export declare const MEARL_EXTENSION_ID = "aoehhjnofngknnjefamjbplchbolghkm";
+export interface BrowserExtensionInstallOptions {
+    force?: boolean;
+    targetDirectory?: string;
+    chromeUserDataDirectory?: string;
+    waitForCdpMs?: number;
+    writeLine?: (line: string) => void;
+}
+export interface BrowserExtensionInstallResult {
+    extensionId?: string;
+    loaded: boolean;
+    path: string;
+    version: string;
+    archiveUrl: string;
+    cdpError?: string;
+}
+export interface BrowserExtensionDependencies {
+    extractArchive?: (archivePath: string, destination: string) => Promise<void>;
+    fetch?: typeof fetch;
+    inspectInstallation?: typeof inspectMearlExtensionViaCdp;
+    loadUnpacked?: typeof loadUnpackedViaCdp;
+    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 loadUnpackedViaCdp(extensionDirectory: string, chromeUserDataDirectory?: string): Promise<{
+    extensionId: string;
+}>;
+export declare function inspectMearlExtensionViaCdp(chromeUserDataDirectory?: string): Promise<InstalledBrowserExtension | null>;
+export declare function installMearlBrowserExtension(options?: BrowserExtensionInstallOptions, dependencies?: BrowserExtensionDependencies): Promise<BrowserExtensionInstallResult>;

package/dist/browserExtension.js

@@ -0,0 +1,406 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import extractZip from 'extract-zip';
+import WebSocket from 'ws';
+import { isMearlReleaseVersion, parseMearlReleaseVersion } from './version.js';
+export const MEARL_EXTENSION_DOWNLOAD_PAGE = 'https://mearl.alibaba-inc.com/';
+export const MEARL_EXTENSION_DIRECTORY_NAME = 'chrome-extension';
+export const MEARL_EXTENSION_ID = 'aoehhjnofngknnjefamjbplchbolghkm';
+const ARCHIVE_PATTERN = /mearl-chrome-v(\d+\.\d+\.\d+(?:-beta\.\d+)?)\.zip/g;
+const MAX_ARCHIVE_BYTES = 64 * 1024 * 1024;
+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';
+    }
+}
+function compareVersions(left, right) {
+    const parsedLeft = parseMearlReleaseVersion(left);
+    const parsedRight = parseMearlReleaseVersion(right);
+    for (const key of ['major', 'minor', 'patch']) {
+        if (parsedLeft[key] !== parsedRight[key])
+            return parsedLeft[key] - parsedRight[key];
+    }
+    if (parsedLeft.channel !== parsedRight.channel)
+        return parsedLeft.channel === 'stable' ? 1 : -1;
+    return (parsedLeft.beta ?? 0) - (parsedRight.beta ?? 0);
+}
+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(compareVersions).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();
+}
+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 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}`;
+}
+export async function loadUnpackedViaCdp(extensionDirectory, chromeUserDataDirectory = resolveChromeUserDataDirectory()) {
+    const connection = await CdpConnection.connect(browserCdpEndpoint(chromeUserDataDirectory));
+    try {
+        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 };
+    }
+    finally {
+        connection.close();
+    }
+}
+export async function inspectMearlExtensionViaCdp(chromeUserDataDirectory = resolveChromeUserDataDirectory()) {
+    const connection = await CdpConnection.connect(browserCdpEndpoint(chromeUserDataDirectory));
+    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(() => { });
+        }
+        connection.close();
+    }
+}
+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;
+}
+export async function installMearlBrowserExtension(options = {}, dependencies = {}) {
+    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 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 parentDirectory = path.dirname(targetDirectory);
+    const stagingDirectory = `${targetDirectory}.staging-${randomUUID()}`;
+    const archivePath = path.join(parentDirectory, `.mearl-extension-${randomUUID()}.zip`);
+    const release = await resolveExtensionArchive(fetchImpl);
+    const chromeUserDataDirectory = options.chromeUserDataDirectory ?? resolveChromeUserDataDirectory();
+    const waitForCdpMs = Math.max(0, options.waitForCdpMs ?? 0);
+    const deadline = Date.now() + waitForCdpMs;
+    let lastFailure;
+    let lastNoticeAt = 0;
+    do {
+        try {
+            const installed = await inspectInstallation(chromeUserDataDirectory);
+            if (installed && !isSetupManagedInstallation(installed, targetDirectory) && !options.force) {
+                throw new BrowserExtensionConflictError(installed);
+            }
+            lastFailure = undefined;
+            break;
+        }
+        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);
+    if (lastFailure) {
+        return {
+            loaded: false,
+            path: targetDirectory,
+            version: release.version,
+            archiveUrl: release.archiveUrl,
+            cdpError: lastFailure,
+        };
+    }
+    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');
+        }
+        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 replaceDirectory(stagingDirectory, targetDirectory);
+    }
+    finally {
+        await fs.promises.rm(archivePath, { force: true });
+        await fs.promises.rm(stagingDirectory, { force: true, recursive: true });
+    }
+    try {
+        const loaded = await loadUnpacked(targetDirectory, chromeUserDataDirectory);
+        return {
+            extensionId: loaded.extensionId,
+            loaded: true,
+            path: targetDirectory,
+            version: release.version,
+            archiveUrl: release.archiveUrl,
+        };
+    }
+    catch (error) {
+        return {
+            loaded: false,
+            path: targetDirectory,
+            version: release.version,
+            archiveUrl: release.archiveUrl,
+            cdpError: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

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,34 @@ 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(`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(`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, findLatestExtensionVersion, installMearlBrowserExtension, inspectMearlExtensionViaCdp, loadUnpackedViaCdp, MEARL_EXTENSION_DIRECTORY_NAME, MEARL_EXTENSION_DOWNLOAD_PAGE, MEARL_EXTENSION_ID, resolveChromeUserDataDirectory, resolveMearlExtensionDirectory, } from './browserExtension.js';
+export type { BrowserExtensionDependencies, BrowserExtensionInstallOptions, BrowserExtensionInstallResult, InstalledBrowserExtension, } 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';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { buildGlobalPackageCommand, detectGlobalPackage, resolveInvokingPackageManager, resolvePackageManagerInstallation, } from './packageManager.js';
 export { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin, } from './agentBay.js';
+export { BrowserExtensionConflictError, extensionArchiveUrl, findLatestExtensionVersion, installMearlBrowserExtension, inspectMearlExtensionViaCdp, loadUnpackedViaCdp, MEARL_EXTENSION_DIRECTORY_NAME, MEARL_EXTENSION_DOWNLOAD_PAGE, MEARL_EXTENSION_ID, resolveChromeUserDataDirectory, resolveMearlExtensionDirectory, } 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';

package/package.json

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