@mearl/client 2.17.1 → 2.19.0

package/README.md

@@ -127,7 +127,29 @@ Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通
 | `--server <url>`         | 覆盖自动读取的 cloud-server 地址      |
 
 `browser_list --help` 和 `browser_launch --help` 会按场景展示宿主选择参数；连接或传输排障运行
-`mearl check --help`。其中 `--json` 仅用于输出机器可读的检查结果。
+`mearl check --help`。`mearl check` 检查连接与浏览器状态；`mearl check --updates` 还会并发查询
+client、native-host、cloud-connector 和扩展的最新发布版本。发布版本查询最长等待约 1.5 秒，
+无法访问发布源时会提示无法确认更新，不影响浏览器可用性检查。`--json` 输出机器可读的检查结果，
+与 `--updates` 同用时包含更新状态。发现更新时会提示适用的命令：client/native-host 使用
+`npx @mearl/setup update`，setup 管理的扩展使用 `npx @mearl/setup extension`。
+
+全局安装的 `mearl` CLI 默认在每天首次使用后启动独立后台进程，查询最新发布版本，并比较
+client、native-host、cloud-server 和 MCP server 的已安装版本。发现更新时调用
+`@mearl/setup update --yes --skip-skill` 更新版本落后的运行环境及其共享 client，也支持独立安装的 CLI。
+当前命令不等待网络或安装；检查和安装结果记录在
+`~/.mearl/cli-auto-update-state.json`。项目依赖和临时 `npx` 副本不会被自动修改。
+浏览器扩展沿用其独立的更新入口。
+在 `~/.mearl/config.json` 中设置间隔天数或关闭自动更新：
+
+```json
+{ "cliAutoUpdate": { "intervalDays": 7 } }
+```
+
+```json
+{ "cliAutoUpdate": false }
+```
+
+间隔按本地日历日计算。需要立即检查各组件的发布版本时，仍可运行 `mearl check --updates`。
 
 ## Skill 插件
 
@@ -136,7 +158,7 @@ Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通
 ```bash
 npx @mearl/setup plugin install trip/mearl --skill yuque-doc-fetch --yes
 npx @mearl/setup plugin install trip/mearl --skill buc-request --yes
-npx @mearl/setup plugin yuque /absolute/path/to/yuque-doc-fetch
+npx @mearl/setup plugin /absolute/path/to/yuque-doc-fetch
 npx @mearl/setup plugin uninstall yuque
 mearl yuque read "https://aliyuque.antfin.com/group/book/doc"
 mearl yuque --payload '{"command":"read","input":{"url":"https://aliyuque.antfin.com/group/book/doc"}}'
@@ -149,9 +171,9 @@ mearl yuque --version
 Provider 与插件仍可独立安装、更新和卸载，帮助聚合不会启动 Provider 或执行业务命令。
 
 目录默认使用 `scripts/main.mjs` 或 `scripts/main.py`；两者同时存在时使用 JavaScript 入口。JavaScript 入口默认导出 `register(app)`，Python 入口导出 `register(app)` 函数；两种入口都可声明简短的 `name` 和 `description`，并通过 `app.command(signature, handler, description?)`
-注册动作、`app.invoke(action, payload, options?)` 复用当前浏览器上下文，并用 `app.progress(message)` 报告可选进度。Python 的 `app.invoke` 是同步调用，handler 可以是普通函数或 `async def`。Python 插件要求 `python3 >= 3.9`，可用 `MEARL_PYTHON` 指定解释器路径；Mearl 不安装 Python 或执行 `pip install`。调用另一个插件时，payload 使用 `{ command, input }` envelope；嵌套调用继承宿主选项并拒绝循环依赖。CLI 默认只输出最终结果，传入
+注册动作、`app.invoke(action, payload, options?)` 复用当前浏览器上下文，并用 `app.progress(message)` 报告可选进度。JavaScript 插件还可传入 `{ message, data }`，让工具页通过可 JSON 序列化的 `data` 获取稳定的阶段、对象 ID 等机器信息；CLI 仍只显示 `message`。Python 的 `app.invoke` 是同步调用，handler 可以是普通函数或 `async def`。Python 插件要求 `python3 >= 3.9`，可用 `MEARL_PYTHON` 指定解释器路径；Mearl 不安装 Python 或执行 `pip install`。调用另一个插件时，payload 使用 `{ command, input }` envelope；嵌套调用继承宿主选项并拒绝循环依赖。CLI 默认只输出最终结果，传入
 `--verbose` 时才把进度写入 stderr。handler 返回文本或 JSON，宿主统一处理 `--output`、连接和错误。写命令在用户调用后直接执行，业务模块负责目标、状态、幂等和结果校验。
-自动注册默认以 skill 安装目录名作为命令名，也可在入口声明 `name` 指定短名称。
+注册名优先使用显式名称，其次读取入口的 `name` metadata，最后回退到 skill 目录名；常规注册只传路径。
 setup 会补齐缺失或低于自身版本的 client、native-host；安装参数透传给 Ali Skills，并固定全局共享安装。
 
 需要单独检查插件时运行 `mearl <name> --version`。命令会解析注册记录并加载入口，但不连接浏览器；
@@ -176,7 +198,7 @@ const result = await invokePlugin(
 );
 ```
 
-MCP Server 通过固定工具 `mearl_plugin` 接受同样的 `plugin`、`command` 和 `input`，不会把插件子命令动态扩展成 MCP 工具。SDK 与 MCP 不接受任意入口路径；调用尚未注册的 `buc` 或 `tdbank` 时，会通过匹配当前 client 版本的 setup 自动安装并重试一次。其他未注册名称返回 `PLUGIN_NOT_REGISTERED`。
+MCP Server 通过固定工具 `plugin_invoke` 接受同样的 `plugin`、`command` 和 `input`，不会把插件子命令动态扩展成 MCP 工具。SDK 与 MCP 不接受任意入口路径；调用尚未注册的 `buc` 或 `tdbank` 时，会通过匹配当前 client 版本的 setup 自动安装并重试一次。其他未注册名称返回 `PLUGIN_NOT_REGISTERED`。
 
 注册记录在 `~/.mearl/plugins/<name>.json`，保存入口路径和可选的简短描述；skill 业务代码原地更新直接生效，换路径或更新描述后重新注册。
 `plugin uninstall <name>` 会对 `~/.agents/skills` 中的全局 Skill 调用 `ali-skills remove --global --yes`，
@@ -186,6 +208,65 @@ MCP Server 通过固定工具 `mearl_plugin` 接受同样的 `plugin`、`command
 卸载清理命令。其他错误按实际原因处理。
 编写规范见 [Mearl Skill Creator 的 Skill 插件规范](../skills/mearl-skill-creator/references/cli-plugin.md)。
 
+插件可选导出 `toolbox`，注册后会出现在扩展 Popup 的工具箱中。页面资源放在 Skill 目录内，注册时由
+Mearl 将入口 HTML 引用的本地 CSS、JavaScript 和图片内联为不可变页面包，不需要启动 HTTP 服务，
+也不要求普通 HTML/CSS/JS 页面自行构建：
+
+```javascript
+export const toolbox = {
+  version: 1,
+  title: '迭代管理',
+  description: '查看多个仓库的改动与发布状态',
+  icon: 'git-branch',
+  locales: {
+    en: {
+      title: 'Iteration Management',
+      description: 'Track changes and release status across repositories',
+    },
+  },
+  agent: {
+    skill: 'iteration-manager',
+    layout: 'workspace',
+  },
+  page: {
+    type: 'sandbox',
+    runtime: 'preact',
+    entry: 'assets/toolbox/index.html',
+    commands: ['list', 'create', 'delete'],
+  },
+  order: 100,
+};
+
+export default function register(app) {
+  app.command('list', async () => ({ items: await listItems() }));
+  app.command('create <name>', async input => ({ item: await createItem(input.name) }));
+  app.command('delete <id>', async input => ({ item: await deleteItem(input.id) }));
+}
+```
+
+声明 `agent` 后工具页可以把任务交给对话 Agent；`layout` 默认为 `drawer`，宿主会提供顶部入口。
+页面也可在 `setAgentPanelVisible` 或 `runAgentTask` 中为单次交互指定 `drawer` / `workspace` / `inline`；
+Agent 对话会保存在 Codex 会话历史中。带固定
+18rem 左侧导航的工作台可默认使用 `workspace`，由导航项切换 Agent，并占满导航栏以外的主内容区；详情页仍可按需唤起右侧抽屉。
+`inline` 用于把 Agent 嵌入工具页中的卡片或分区，调用时同时传入作为占位区域的 `anchor` 元素和稳定的
+`key`；宿主会跟随该元素的滚动与尺寸变化同步面板位置。`key` 也可用于抽屉或工作区布局，为不同业务对象
+隔离会话与输入草稿；`setAgentPanelVisible` 可同时传入绝对路径 `cwd`，让首次创建的会话直接绑定该目录。
+传入 `context` 可为面板提供不显示为聊天消息的背景上下文；它会在用户首次发送消息、创建会话时作为
+developer instructions 交给 Agent。
+
+页面通过 `await window.mearl.ready()` 取得 `{ locale, theme, title, fontSize }`，通过
+`window.mearl.invoke(command, input?)` 调用 `commands` 白名单中的同一插件命令。页面运行在无扩展
+API、默认不可联网的 sandbox iframe 中；Native Host 校验插件身份、命令白名单和消息大小。页面包按
+内容哈希缓存并分块传输，因此不会增加 Popup 的启动开销。使用模块脚本时需先打包为不再包含 `import`
+的单文件；React、Vue 等工程可以把构建后的 `index.html` 作为 `entry`，注册流程仍负责最终资源封装。
+需要无构建的组件与状态管理时可声明 `page.runtime: 'preact'`，扩展会在页面完整性校验后注入固定的
+Preact、Hooks 和 HTM 运行时。页面从 `window.mearl.ui` 读取 `html`、`render`、`useState` 等 API；
+`window.mearl.ui.version` 仅用于诊断，插件不能选择运行时版本。
+宿主会同步扩展主题、字号，并注入 `--mearl-bg-primary`、`--mearl-bg-secondary`、
+`--mearl-text-primary`、`--mearl-text-secondary`、`--mearl-border`、`--mearl-bg-hover` 和
+`--mearl-accent` 等语义变量；主操作按钮使用 `--mearl-action-primary`、
+`--mearl-action-primary-hover` 和 `--mearl-action-primary-text`，以保持与扩展按钮一致。
+
 需要 BUC 身份的内部 HTTP 接口通过官方 `buc` 插件调用。CLI 使用 `mearl buc request`，业务插件使用
 `app.invoke('buc', { command: 'request', input })`；当前身份和人员资料分别使用 `whoami` 与 `profile`
 子命令。BUC 插件按请求创建一次性凭据，只接受无 URL 凭据的 HTTPS 地址，过滤认证字段与 Cookie；

package/dist/autoUpdate.d.ts

@@ -0,0 +1,33 @@
+export type InstalledMearlEnvironment = {
+    profile: 'local' | 'cloud' | 'mcp';
+    version: string;
+};
+interface ScheduleOptions {
+    intervalDays?: number | null;
+    packageRoot?: string | null;
+    now?: Date;
+    statePath?: string;
+    lockPath?: string;
+    workerPath?: string;
+    launch?: (worker: string, installedVersion: string, packageRoot: string, token: string) => void;
+}
+interface WorkerOptions {
+    fetchLatestVersion?: () => Promise<string>;
+    getInstalledEnvironments?: () => InstalledMearlEnvironment[];
+    update?: (version: string, packageRoot: string, profiles: InstalledMearlEnvironment['profile'][], updateClient: boolean) => Promise<void>;
+    now?: Date;
+    statePath?: string;
+    lockPath?: string;
+}
+export declare function isCliUpdateDue(lastCheckDate: string | undefined, now: Date, intervalDays: number): boolean;
+export declare function isGlobalClientPackageRoot(packageRoot: string, platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): boolean;
+/** Queue a detached check after the CLI command has finished. */
+export declare function scheduleCliAutoUpdate(installedVersion: string, options?: ScheduleOptions): void;
+export declare function setupUpdateCommand(version: string, packageRoot: string, profiles: InstalledMearlEnvironment['profile'][], updateClient: boolean): {
+    command: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+};
+/** Runs only in the detached worker process. */
+export declare function runCliAutoUpdate(installedVersion: string, packageRoot: string, token: string, options?: WorkerOptions): Promise<void>;
+export {};

package/dist/autoUpdate.js

@@ -0,0 +1,359 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, join, resolve, win32 } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isNewerRelease, parseReleaseVersion } from './check.js';
+import { loadCliAutoUpdateIntervalDays } from './unifiedConfig.js';
+const CONFIG_DIR = join(homedir(), '.mearl');
+const STATE_PATH = join(CONFIG_DIR, 'cli-auto-update-state.json');
+const LOCK_PATH = join(CONFIG_DIR, 'cli-auto-update.lock');
+const LOCK_STALE_MS = 10 * 60_000;
+const UPDATE_TIMEOUT_MS = 5 * 60_000;
+const VERSION_URL = 'https://registry.npmjs.org/@mearl%2Fclient/latest';
+function localDate(date) {
+    return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+}
+function dayNumber(value) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    if (!match)
+        return null;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const timestamp = Date.UTC(year, month - 1, day);
+    const date = new Date(timestamp);
+    return date.getUTCFullYear() === year &&
+        date.getUTCMonth() + 1 === month &&
+        date.getUTCDate() === day
+        ? timestamp / 86_400_000
+        : null;
+}
+export function isCliUpdateDue(lastCheckDate, now, intervalDays) {
+    const previous = typeof lastCheckDate === 'string' ? dayNumber(lastCheckDate) : null;
+    const today = dayNumber(localDate(now));
+    return (previous === null || today === null || today < previous || today - previous >= intervalDays);
+}
+export function isGlobalClientPackageRoot(packageRoot, platform = process.platform, env = process.env) {
+    const resolvedRoot = platform === 'win32' ? win32.resolve(packageRoot) : resolve(packageRoot);
+    const normalized = resolvedRoot.replaceAll('\\', '/').toLowerCase();
+    if (!normalized.endsWith('/node_modules/@mearl/client'))
+        return false;
+    const pnpmGlobalRoot = /\/global\/\d+\/(?:\.pnpm\/.*\/)?node_modules\//.exec(normalized);
+    if (pnpmGlobalRoot) {
+        const pnpmHome = resolvedRoot.slice(0, pnpmGlobalRoot.index);
+        return existsSync(join(pnpmHome, platform === 'win32' ? 'mearl.cmd' : 'mearl'));
+    }
+    if (normalized.includes('/.volta/tools/image/packages/'))
+        return true;
+    const npmSuffix = '/lib/node_modules/@mearl/client';
+    if (platform !== 'win32' && normalized.endsWith(npmSuffix)) {
+        const prefix = resolvedRoot.slice(0, -npmSuffix.length);
+        try {
+            return (realpathSync(join(prefix, 'bin', 'mearl')) ===
+                realpathSync(join(packageRoot, 'dist', 'bin.js')));
+        }
+        catch {
+            return false;
+        }
+    }
+    const windowsNpmRoot = platform === 'win32' && env.APPDATA
+        ? `${win32.resolve(env.APPDATA).replaceAll('\\', '/').toLowerCase()}/npm/node_modules/@mearl/client`
+        : null;
+    return (normalized.includes('/.bun/install/global/') ||
+        /\/(?:\.config\/yarn|\.yarn|yarn\/data|yarn)\/global\//.test(normalized) ||
+        (platform === 'win32' && normalized === windowsNpmRoot));
+}
+function globalSearchPath(pathValue) {
+    return pathValue
+        ?.split(delimiter)
+        .filter(directory => !/(?:^|[\\/])node_modules[\\/]\.bin[\\/]?$/i.test(directory))
+        .join(delimiter);
+}
+function currentGlobalClientRoot() {
+    let directory = dirname(realpathSync(fileURLToPath(import.meta.url)));
+    for (let depth = 0; depth < 12; depth += 1) {
+        try {
+            const manifest = JSON.parse(readFileSync(join(directory, 'package.json'), 'utf8'));
+            if (manifest.name === '@mearl/client') {
+                return isGlobalClientPackageRoot(directory) ? directory : null;
+            }
+        }
+        catch {
+            // Continue toward the package root.
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return null;
+}
+function readState(statePath) {
+    try {
+        const value = JSON.parse(readFileSync(statePath, 'utf8'));
+        return value && typeof value === 'object' && !Array.isArray(value)
+            ? value
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeState(statePath, state) {
+    mkdirSync(dirname(statePath), { recursive: true, mode: 0o700 });
+    const temporary = `${statePath}.${process.pid}.tmp`;
+    try {
+        writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+        renameSync(temporary, statePath);
+    }
+    catch (error) {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            /* No temporary file to remove. */
+        }
+        throw error;
+    }
+}
+function acquireLock(lockPath, token) {
+    mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const descriptor = openSync(lockPath, 'wx', 0o600);
+            try {
+                writeFileSync(descriptor, token);
+            }
+            finally {
+                closeSync(descriptor);
+            }
+            return true;
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !('code' in error) || error.code !== 'EEXIST')
+                throw error;
+            try {
+                if (Date.now() - statSync(lockPath).mtimeMs <= LOCK_STALE_MS)
+                    return false;
+                unlinkSync(lockPath);
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+    return false;
+}
+function releaseLock(lockPath, token) {
+    try {
+        if (readFileSync(lockPath, 'utf8') === token)
+            unlinkSync(lockPath);
+    }
+    catch {
+        // A missing lock does not affect the current command or update result.
+    }
+}
+function launchWorker(worker, version, packageRoot, token) {
+    const child = spawn(process.execPath, [worker, version, packageRoot, token], {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+    child.once('error', () => releaseLock(LOCK_PATH, token));
+    child.unref();
+}
+/** Queue a detached check after the CLI command has finished. */
+export function scheduleCliAutoUpdate(installedVersion, options = {}) {
+    try {
+        const intervalDays = options.intervalDays === undefined ? loadCliAutoUpdateIntervalDays() : options.intervalDays;
+        if (intervalDays === null)
+            return;
+        const packageRoot = options.packageRoot === undefined ? currentGlobalClientRoot() : options.packageRoot;
+        if (!packageRoot)
+            return;
+        const now = options.now ?? new Date();
+        const statePath = options.statePath ?? STATE_PATH;
+        const lockPath = options.lockPath ?? LOCK_PATH;
+        if (!isCliUpdateDue(readState(statePath).lastCheckDate, now, intervalDays))
+            return;
+        const token = randomUUID();
+        if (!acquireLock(lockPath, token))
+            return;
+        let launched = false;
+        try {
+            if (!isCliUpdateDue(readState(statePath).lastCheckDate, now, intervalDays))
+                return;
+            const worker = options.workerPath ?? fileURLToPath(new URL('./autoUpdateWorker.js', import.meta.url));
+            if (!existsSync(worker))
+                return;
+            (options.launch ?? launchWorker)(worker, installedVersion, packageRoot, token);
+            launched = true;
+        }
+        finally {
+            if (!launched)
+                releaseLock(lockPath, token);
+        }
+    }
+    catch {
+        // Update scheduling must never change CLI behavior.
+    }
+}
+export function setupUpdateCommand(version, packageRoot, profiles, updateClient) {
+    if (profiles.length === 0 && !updateClient) {
+        throw new Error('An update target is required');
+    }
+    if (!parseReleaseVersion(version))
+        throw new Error('A valid Mearl release is required');
+    const [major, minor] = version.split('.');
+    const env = { ...process.env };
+    delete env.MEARL_AUTO_UPDATE_CLIENT_ROOT;
+    delete env.MEARL_AUTO_UPDATE_CLIENT_ONLY;
+    delete env.MEARL_AUTO_UPDATE_PROFILES;
+    env.MEARL_AUTO_UPDATE_SEARCH_PATH = globalSearchPath(env.PATH);
+    if (updateClient || profiles.some(profile => profile === 'local' || profile === 'cloud')) {
+        env.MEARL_AUTO_UPDATE_CLIENT_ROOT = packageRoot;
+    }
+    if (profiles.length === 0)
+        env.MEARL_AUTO_UPDATE_CLIENT_ONLY = '1';
+    else
+        env.MEARL_AUTO_UPDATE_PROFILES = profiles.join(',');
+    return {
+        command: 'npx',
+        args: [
+            '--yes',
+            `@mearl/setup@${version}`,
+            'update',
+            '--yes',
+            '--target-line',
+            `${major}.${minor}.x`,
+            '--skip-skill',
+        ],
+        env,
+    };
+}
+function updateWithSetup(version, packageRoot, profiles, updateClient) {
+    const { command, args, env } = setupUpdateCommand(version, packageRoot, profiles, updateClient);
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            env,
+            stdio: 'ignore',
+            windowsHide: true,
+            shell: process.platform === 'win32',
+        });
+        const timeout = setTimeout(() => child.kill(), UPDATE_TIMEOUT_MS);
+        child.once('error', error => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+        child.once('close', code => {
+            clearTimeout(timeout);
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`Setup exited with code ${code ?? 'unknown'}`));
+        });
+    });
+}
+function installedEnvironments() {
+    const versions = [];
+    const env = { ...process.env, PATH: globalSearchPath(process.env.PATH) };
+    const executables = [
+        { profile: 'local', executable: 'mearl-native-host' },
+        { profile: 'cloud', executable: 'mearl-cloud-server' },
+        { profile: 'mcp', executable: 'mearl-mcp-server' },
+    ];
+    for (const { profile, executable } of executables) {
+        try {
+            const result = spawnSync(executable, ['--version'], {
+                encoding: 'utf8',
+                timeout: 5_000,
+                maxBuffer: 1_024,
+                windowsHide: true,
+                shell: process.platform === 'win32',
+                env,
+            });
+            const version = result.stdout?.trim();
+            if (result.status === 0 && typeof version === 'string' && parseReleaseVersion(version)) {
+                versions.push({ profile, version });
+            }
+        }
+        catch {
+            // Other installed environments can still be checked and updated.
+        }
+    }
+    return versions;
+}
+async function fetchLatestClientVersion() {
+    const response = await fetch(VERSION_URL, { signal: AbortSignal.timeout(2_000) });
+    if (!response.ok)
+        throw new Error(`Registry returned HTTP ${response.status}`);
+    const payload = (await response.json());
+    const version = payload.version;
+    if (typeof version !== 'string') {
+        throw new Error('Registry returned an invalid release version');
+    }
+    return version;
+}
+/** Runs only in the detached worker process. */
+export async function runCliAutoUpdate(installedVersion, packageRoot, token, options = {}) {
+    const statePath = options.statePath ?? STATE_PATH;
+    const lockPath = options.lockPath ?? LOCK_PATH;
+    try {
+        writeState(statePath, {
+            ...readState(statePath),
+            lastCheckDate: localDate(options.now ?? new Date()),
+        });
+    }
+    catch {
+        releaseLock(lockPath, token);
+        return;
+    }
+    let result;
+    try {
+        const version = await (options.fetchLatestVersion ?? fetchLatestClientVersion)();
+        if (!parseReleaseVersion(version))
+            throw new Error('Registry returned an invalid release version');
+        const environments = (options.getInstalledEnvironments ?? installedEnvironments)();
+        const installedVersions = [
+            installedVersion,
+            ...environments.map(environment => environment.version),
+        ];
+        const updateClient = isNewerRelease(version, installedVersion);
+        const staleProfiles = environments
+            .filter(environment => isNewerRelease(version, environment.version))
+            .map(environment => environment.profile);
+        const updateAvailable = updateClient || staleProfiles.length > 0;
+        const newerInstalled = installedVersions.some(installed => isNewerRelease(installed, version));
+        if (updateAvailable && newerInstalled) {
+            result = {
+                checkedAt: new Date().toISOString(),
+                status: 'skipped',
+                version,
+                error: 'An installed component is newer than the latest published release',
+            };
+        }
+        else if (updateAvailable) {
+            await (options.update ?? updateWithSetup)(version, packageRoot, staleProfiles, updateClient);
+            result = { checkedAt: new Date().toISOString(), status: 'updated', version };
+        }
+        else {
+            result = { checkedAt: new Date().toISOString(), status: 'current', version };
+        }
+    }
+    catch (error) {
+        result = {
+            checkedAt: new Date().toISOString(),
+            status: 'failed',
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    try {
+        writeState(statePath, { ...readState(statePath), lastResult: result });
+    }
+    catch {
+        /* The result is best effort. */
+    }
+    releaseLock(lockPath, token);
+}

package/dist/autoUpdateWorker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/autoUpdateWorker.js

@@ -0,0 +1,5 @@
+import { runCliAutoUpdate } from './autoUpdate.js';
+const [installedVersion, packageRoot, token] = process.argv.slice(2);
+if (installedVersion && packageRoot && token) {
+    await runCliAutoUpdate(installedVersion, packageRoot, token);
+}

package/dist/bin.js

@@ -1,3 +1,6 @@
 #!/usr/bin/env node
 import { runMearlCli } from './cli.js';
+import { CLIENT_VERSION } from './socket.js';
+import { scheduleCliAutoUpdate } from './autoUpdate.js';
 process.exitCode = await runMearlCli(process.argv.slice(2));
+scheduleCliAutoUpdate(CLIENT_VERSION);

package/dist/check.d.ts

@@ -67,6 +67,13 @@ export interface UnifiedCheckResult {
     connectors: CloudConnectorInfo[];
     environment: CheckItem[];
     ok: boolean;
+    updates?: UnifiedCheckUpdate[];
+}
+export interface UnifiedCheckUpdate {
+    component: string;
+    installed: string;
+    latest?: string;
+    status: 'current' | 'available' | 'unavailable';
 }
 interface CheckClient {
     invoke(action: string, data?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
@@ -82,12 +89,16 @@ export interface UnifiedCheckOptions {
     local?: boolean;
     transport?: 'cdp';
     json?: boolean;
+    checkUpdates?: boolean;
 }
 export interface UnifiedCheckDependencies {
     createClient?: (options: UnifiedClientOptions) => CheckClient;
     writeJson?: (json: string) => void;
     writeLine?: (line: string) => void;
+    fetchLatestVersion?: (component: string) => Promise<string>;
 }
+export declare function parseReleaseVersion(value: unknown): number[] | null;
+export declare function isNewerRelease(latest: string, installed: string): boolean;
 export declare function parseCheckTimeout(value: string | undefined): number | null;
 export declare function runUnifiedCheck(options: UnifiedCheckOptions & {
     json: true;