@mearl/setup 2.8.1 → 2.9.0

package/README.md

@@ -47,8 +47,10 @@ npx @mearl/setup agentbay
 - `--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 与浏览器存储保持稳定。
+  `~/.mearl/chrome-extension`。首次安装通过浏览器级 CDP 的 `Extensions.loadUnpacked`
+  加载；后续更新由 `mearl check --local --json` 确认当前扩展仍来自 setup 管理目录后，直接替换
+  文件并通过 Native Host 触发扩展 reload。固定目录和 manifest 中的 `key` 保证扩展 ID
+  与浏览器存储保持稳定。
 - 下载前会通过 CDP 检查同 ID 插件的来源。未安装，或来源为固定目录中的 `UNPACKED`
   插件时可继续；Chrome 商店、企业策略或其他本地目录安装的版本默认保持不变。只有显式
   传入 `--force` 才会接管并替换这些版本。
@@ -59,14 +61,26 @@ npx @mearl/setup agentbay
 npx @mearl/setup extension
 ```
 
-如果 Chrome 尚未开放 CDP，交互命令会提示打开
+首次安装、旧版 setup 扩展首次迁移，或 Native Host reload 不可用时才需要 CDP。如果
+Chrome 尚未开放 CDP，交互命令会提示打开
 `chrome://inspect/#remote-debugging`、启用远程调试并允许连接，然后等待安装完成。无 TTY
-环境使用 `npx @mearl/setup extension --yes`；它只尝试一次。CDP 不可用时不会下载或修改
-插件目录，打开 CDP 后重新执行同一命令即可。
+环境使用 `npx @mearl/setup extension --yes`；它只尝试一次。无法确认 setup 管理来源且
+CDP 不可用时不会下载或修改插件目录，打开 CDP 后重新执行同一命令即可。
 
 该命令每次都读取下载页上的最新插件版本，不要求与 setup、CLI 或 Native Host 同版本。
-已经从固定目录安装过时，新版本会先替换目录，再对同一路径调用
-`Extensions.loadUnpacked`，Chrome 会重载现有 unpacked 扩展。
+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()` 主动检查。
 
 ## 跟随浏览器扩展自动更新
 

package/dist/browserExtension.d.ts

@@ -1,15 +1,32 @@
 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;
@@ -17,10 +34,13 @@ export interface BrowserExtensionInstallResult {
     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 {
@@ -38,8 +58,21 @@ export declare function resolveChromeUserDataDirectory(platform?: NodeJS.Platfor
 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

@@ -1,15 +1,20 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { randomUUID } from 'node:crypto';
+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 { isMearlReleaseVersion, parseMearlReleaseVersion } from './version.js';
+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) {
@@ -18,17 +23,6 @@ export class BrowserExtensionConflictError extends Error {
         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');
@@ -43,7 +37,7 @@ export function resolveMearlExtensionDirectory(home = os.homedir()) {
 }
 export function findLatestExtensionVersion(html) {
     const versions = Array.from(html.matchAll(ARCHIVE_PATTERN), match => match[1]).filter(isMearlReleaseVersion);
-    return versions.sort(compareVersions).at(-1) ?? null;
+    return versions.sort(compareMearlReleaseVersions).at(-1) ?? null;
 }
 export function extensionArchiveUrl(version) {
     if (!isMearlReleaseVersion(version)) {
@@ -51,6 +45,42 @@ export function extensionArchiveUrl(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) {
@@ -189,36 +219,38 @@ function sameExtensionPath(left, right) {
 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}`;
 }
-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));
+async function inspectInstallationWithConnection(connection) {
     const target = await connection.send('Target.createTarget', {
         background: true,
         url: 'chrome://extensions-internals',
@@ -259,9 +291,82 @@ export async function inspectMearlExtensionViaCdp(chromeUserDataDirectory = reso
         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);
@@ -300,63 +405,11 @@ function readExtensionManifest(directory) {
     }
     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());
+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`);
-    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' });
@@ -371,6 +424,12 @@ export async function installMearlBrowserExtension(options = {}, dependencies =
         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);
@@ -378,29 +437,177 @@ export async function installMearlBrowserExtension(options = {}, dependencies =
         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 options.force ? null : inspectInstallation(chromeUserDataDirectory);
+        }
+        const candidate = await connectCdp(chromeUserDataDirectory);
+        try {
+            const installed = options.force ? null : 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 {
-        const loaded = await loadUnpacked(targetDirectory, chromeUserDataDirectory);
-        return {
-            extensionId: loaded.extensionId,
-            loaded: true,
-            path: targetDirectory,
-            version: release.version,
-            archiveUrl: release.archiveUrl,
-        };
+        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),
+            };
+        }
     }
-    catch (error) {
-        return {
-            loaded: false,
-            path: targetDirectory,
-            version: release.version,
-            archiveUrl: release.archiveUrl,
-            cdpError: error instanceof Error ? error.message : String(error),
-        };
+    finally {
+        cdpSession?.close();
     }
 }

package/dist/cli.js

@@ -1,132 +1,140 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
+import { Command, CommanderError } from 'commander';
 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);
 export const SETUP_VERSION = require('../package.json').version;
-export function parseSetupArgs(argv) {
-    if (argv.includes('--help') || argv.includes('-h')) {
-        return { agentBayReadStdin: false, help: true, skipSkill: false, yes: false };
+const baseParsedArgs = () => ({
+    agentBayReadStdin: false,
+    help: false,
+    skipSkill: false,
+    yes: false,
+});
+function commanderError(error) {
+    const message = error.message.replace(/^error:\s*/i, '');
+    if (error.code === 'commander.unknownCommand') {
+        return new Error(message.replace(/^unknown command/i, 'Unknown operation'));
     }
-    if (argv.includes('--version') || argv.includes('-v')) {
-        return {
-            agentBayReadStdin: false,
-            help: false,
-            skipSkill: false,
-            version: true,
-            yes: false,
-        };
+    if (error.code === 'commander.unknownOption') {
+        return new Error(message.replace(/^unknown option/i, 'Unknown option'));
     }
-    const firstArg = argv[0];
-    const operation = firstArg === undefined || firstArg.startsWith('-') ? 'install' : firstArg;
-    const optionStart = operation === firstArg ? 1 : 0;
-    if (operation === 'agentbay') {
-        if (argv.length === 1) {
-            return {
-                agentBayReadStdin: false,
-                help: false,
+    return new Error(message);
+}
+export function parseSetupArgs(argv) {
+    let parsed;
+    const program = new Command()
+        .name('mearl-setup')
+        .version(SETUP_VERSION, '-v, --version')
+        .exitOverride()
+        .configureOutput({ writeErr: () => { }, writeOut: () => { } });
+    const addLifecycleCommand = (operation) => {
+        const command = new Command(operation)
+            .exitOverride()
+            .configureOutput({ writeErr: () => { }, writeOut: () => { } })
+            .option('--local')
+            .option('--cloud')
+            .option('--qoder-cloud')
+            .option('--mcp')
+            .option('--target-line <major.minor.x>')
+            .option('--skip-skill')
+            .option('-y, --yes')
+            .option('--non-interactive')
+            .action(() => {
+            const options = command.opts();
+            if (options.cloud && options.qoderCloud) {
+                throw new Error('--cloud and --qoder-cloud cannot be used together');
+            }
+            if (options.targetLine && !isMearlReleaseLine(options.targetLine)) {
+                throw new Error('--target-line requires a valid Mearl release line such as 2.3.x');
+            }
+            if (operation === 'uninstall' && options.targetLine) {
+                throw new Error('--target-line is not available for uninstall');
+            }
+            const profiles = [];
+            if (options.local)
+                profiles.push('local');
+            if (options.cloud || options.qoderCloud)
+                profiles.push('cloud');
+            if (options.mcp)
+                profiles.push('mcp');
+            parsed = {
+                ...baseParsedArgs(),
                 operation,
-                skipSkill: false,
-                yes: false,
+                ...(options.cloud || options.qoderCloud
+                    ? { cloudMode: options.qoderCloud ? 'qoder' : 'websocket' }
+                    : {}),
+                ...(profiles.length > 0 ? { profiles } : {}),
+                skipSkill: options.skipSkill === true,
+                targetLine: options.targetLine,
+                yes: options.yes === true || options.nonInteractive === true,
             };
+        });
+        program.addCommand(command);
+    };
+    addLifecycleCommand('install');
+    addLifecycleCommand('update');
+    addLifecycleCommand('uninstall');
+    const extension = new Command('extension')
+        .exitOverride()
+        .configureOutput({ writeErr: () => { }, writeOut: () => { } })
+        .option('--force')
+        .option('-y, --yes')
+        .option('--non-interactive')
+        .action(() => {
+        const options = extension.opts();
+        parsed = {
+            ...baseParsedArgs(),
+            ...(options.force ? { force: true } : {}),
+            operation: 'extension',
+            yes: options.yes === true || options.nonInteractive === true,
+        };
+    });
+    program.addCommand(extension);
+    const agentbay = new Command('agentbay')
+        .exitOverride()
+        .configureOutput({ writeErr: () => { }, writeOut: () => { } })
+        .argument('[api-key]')
+        .option('--stdin')
+        .option('--key-file <path>')
+        .action((apiKey) => {
+        const options = agentbay.opts();
+        if (apiKey) {
+            throw new Error('API keys are not accepted as command-line arguments');
         }
-        if (argv.length === 2 && argv[1] === '--stdin') {
-            return {
-                agentBayReadStdin: true,
-                help: false,
-                operation,
-                skipSkill: false,
-                yes: false,
-            };
+        if (options.stdin && options.keyFile) {
+            throw new Error('--stdin and --key-file cannot be used together');
         }
-        if (argv.length === 3 && argv[1] === '--key-file' && argv[2]?.trim()) {
-            return {
-                agentBayKeyFile: argv[2],
-                agentBayReadStdin: false,
-                help: false,
-                operation,
-                skipSkill: false,
-                yes: false,
-            };
+        if (options.keyFile !== undefined && !options.keyFile.trim()) {
+            throw new Error('--key-file requires a non-empty path');
         }
-        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)),
+        parsed = {
+            ...baseParsedArgs(),
+            ...(options.keyFile ? { agentBayKeyFile: options.keyFile } : {}),
+            agentBayReadStdin: options.stdin === true,
+            operation: 'agentbay',
         };
+    });
+    program.addCommand(agentbay);
+    const normalizedArgv = argv[0] === undefined || argv[0].startsWith('-') ? ['install', ...argv] : argv;
+    try {
+        program.parse(['node', 'mearl-setup', ...normalizedArgv]);
     }
-    if (operation !== 'install' && operation !== 'update' && operation !== 'uninstall') {
-        throw new Error(`Unknown operation: ${operation}`);
-    }
-    const profiles = [];
-    let skipSkill = false;
-    let targetLine;
-    let yes = false;
-    let cloudMode;
-    for (let index = optionStart; index < argv.length; index += 1) {
-        const arg = argv[index];
-        if (arg === '--yes' || arg === '-y' || arg === '--non-interactive') {
-            yes = true;
-            continue;
-        }
-        if (arg === '--skip-skill') {
-            skipSkill = true;
-            continue;
-        }
-        if (arg === '--target-line') {
-            const value = argv[index + 1];
-            if (!isMearlReleaseLine(value)) {
-                throw new Error('--target-line requires a valid Mearl release line such as 2.3.x');
-            }
-            targetLine = value;
-            index += 1;
-            continue;
-        }
-        if (arg === '--cloud' || arg === '--qoder-cloud') {
-            const requestedMode = arg === '--qoder-cloud' ? 'qoder' : 'websocket';
-            if (cloudMode && cloudMode !== requestedMode) {
-                throw new Error('--cloud and --qoder-cloud cannot be used together');
-            }
-            cloudMode = requestedMode;
+    catch (error) {
+        if (error instanceof CommanderError) {
+            if (error.code === 'commander.helpDisplayed')
+                return { ...baseParsedArgs(), help: true };
+            if (error.code === 'commander.version')
+                return { ...baseParsedArgs(), version: true };
+            throw commanderError(error);
         }
-        const candidate = arg === '--local'
-            ? 'local'
-            : arg === '--cloud' || arg === '--qoder-cloud'
-                ? 'cloud'
-                : arg === '--mcp'
-                    ? 'mcp'
-                    : undefined;
-        if (!candidate)
-            throw new Error(`Unknown option: ${arg}`);
-        if (!profiles.includes(candidate))
-            profiles.push(candidate);
-    }
-    if (operation === 'uninstall' && targetLine) {
-        throw new Error('--target-line is not available for uninstall');
+        throw error;
     }
-    return {
-        agentBayReadStdin: false,
-        help: false,
-        operation,
-        ...(cloudMode ? { cloudMode } : {}),
-        ...(profiles.length > 0 ? { profiles } : {}),
-        skipSkill,
-        targetLine,
-        yes,
-    };
+    if (!parsed)
+        throw new Error('No setup operation was selected');
+    return parsed;
 }
 function printHelp(toError = false) {
     const output = `Mearl Setup v${SETUP_VERSION}
@@ -235,12 +243,16 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
                 writeLine: line => console.error(line),
             });
             if (result.loaded) {
-                console.error(`Browser extension v${result.version} installed or reloaded through CDP.`);
+                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(`Browser extension v${result.version} was not installed.`);
+            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');

package/dist/index.d.ts

@@ -1,7 +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 { 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';
@@ -9,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,7 +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 { 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.1",
+  "version": "2.9.0",
   "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": {
@@ -52,14 +56,16 @@
   ],
   "license": "ISC",
   "engines": {
-    "node": ">=18"
+    "node": ">=22.12.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
+    "commander": "^15.0.0",
     "extract-zip": "^2.0.1",
-    "ws": "^8.18.3"
+    "ws": "^8.18.3",
+    "@mearl/client": "2.9.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",