@mearl/client 3.0.0 → 3.0.2

package/README.en.md

@@ -15,9 +15,9 @@ Use type-safe named methods such as `getRequests` and `sendRequest`, or the flex
 ## Installation
 
 ```bash
-npm install @mearl/client@3
+npm install @mearl/client
 # Or
-pnpm add @mearl/client@3
+pnpm add @mearl/client
 ```
 
 ## SDK usage
@@ -66,7 +66,7 @@ mearl check
 mearl check --local --json
 
 # Update the local environment
-npx @mearl/setup@3 update --local
+npx @mearl/setup update --local
 
 # Show action help
 mearl <action> --help
@@ -248,7 +248,7 @@ Mearl aggregates local and configured cloud-server browsers by default, routing
 latest client, native-host, cloud-connector, and extension releases. Release queries wait about 1.5 seconds at most;
 unreachable sources report unconfirmed updates without affecting browser checks. `--json` returns machine-readable results,
 including updates when combined with `--updates`. Available updates show appropriate commands: client/native-host use
-`npx @mearl/setup@3 update`; setup-managed extensions use `npx @mearl/setup extension`.
+`npx @mearl/setup update`; setup-managed extensions use `npx @mearl/setup extension`.
 
 By default, globally installed `mearl` launches an independent background updater after the first use each day to query releases and compare
 installed client, native-host, cloud-server, and MCP server versions. When needed, it invokes

package/README.md

@@ -15,9 +15,9 @@
 ## 安装
 
 ```bash
-npm install @mearl/client@3
+npm install @mearl/client
 # 或
-pnpm add @mearl/client@3
+pnpm add @mearl/client
 ```
 
 ## SDK 使用
@@ -66,7 +66,7 @@ mearl check
 mearl check --local --json
 
 # 更新本地环境
-npx @mearl/setup@3 update --local
+npx @mearl/setup update --local
 
 # 查看某个 action 的帮助
 mearl <action> --help
@@ -248,7 +248,7 @@ Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通
 client、native-host、cloud-connector 和扩展的最新发布版本。发布版本查询最长等待约 1.5 秒，
 无法访问发布源时会提示无法确认更新，不影响浏览器可用性检查。`--json` 输出机器可读的检查结果，
 与 `--updates` 同用时包含更新状态。发现更新时会提示适用的命令：client/native-host 使用
-`npx @mearl/setup@3 update`，setup 管理的扩展使用 `npx @mearl/setup extension`。
+`npx @mearl/setup update`，setup 管理的扩展使用 `npx @mearl/setup extension`。
 
 全局安装的 `mearl` CLI 默认在每天首次使用后启动独立后台进程，查询最新发布版本，并比较
 client、native-host、cloud-server 和 MCP server 的已安装版本。发现更新时调用

package/dist/plugins/officialPluginCatalog.d.ts

@@ -21,5 +21,7 @@ export declare function validateOfficialPluginCatalog(value: unknown): PluginCat
 export declare function readOfficialPluginCatalog(): PluginCatalog | undefined;
 /** Installation hosts persist only the catalog selected by an approved preset. */
 export declare function replaceOfficialPluginCatalog(revision: string, plugins: Record<string, OfficialPluginDefinition>, selection?: PluginCatalogSelection): void;
+/** Remove only registrations owned by the catalog for the exact active selection. */
+export declare function uninstallOfficialPluginCatalog(selection: PluginCatalogSelection): void;
 export declare function findOfficialPlugin(name: string): OfficialPluginDefinition | undefined;
 export declare function listOfficialPluginNames(setup?: string): string[];

package/dist/plugins/officialPluginCatalog.js

@@ -1,7 +1,7 @@
-import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
 import { createHash, randomUUID } from 'node:crypto';
 import { isAbsolute, join } from 'node:path';
-import { assertPluginName, pluginDirectory } from './pluginRegistry.js';
+import { assertPluginName, findPluginRegistration, pluginDirectory, unregisterPlugin, } from './pluginRegistry.js';
 export const OFFICIAL_PLUGIN_MANAGER = '@mearl/setup:official';
 export const OFFICIAL_PLUGINS = {};
 const MAX_CATALOG_BYTES = 256 * 1024;
@@ -10,12 +10,27 @@ export function validateOfficialPluginCatalog(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new Error('Invalid managed plugin catalog');
     const input = value;
-    if (input.schemaVersion !== 1 || typeof input.revision !== 'string' || !/^[a-f0-9]{64}$/.test(input.revision) ||
-        !input.plugins || typeof input.plugins !== 'object' || Array.isArray(input.plugins) ||
-        Object.keys(input).some(key => !['schemaVersion', 'revision', 'plugins', 'selection'].includes(key)) || Object.keys(input.plugins).length > 200)
+    if (input.schemaVersion !== 1 ||
+        typeof input.revision !== 'string' ||
+        !/^[a-f0-9]{64}$/.test(input.revision) ||
+        !input.plugins ||
+        typeof input.plugins !== 'object' ||
+        Array.isArray(input.plugins) ||
+        Object.keys(input).some(key => !['schemaVersion', 'revision', 'plugins', 'selection'].includes(key)) ||
+        Object.keys(input.plugins).length > 200)
         throw new Error('Invalid managed plugin catalog');
     const selection = input.selection;
-    if (selection !== undefined && (!selection || typeof selection !== 'object' || Array.isArray(selection) || Object.keys(selection).some(key => !['path', 'sha256'].includes(key)) || typeof selection.path !== 'string' || !isAbsolute(selection.path) || selection.path.length > 4096 || /[\0\r\n]/.test(selection.path) || typeof selection.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(selection.sha256)))
+    if (selection !== undefined &&
+        (!selection ||
+            typeof selection !== 'object' ||
+            Array.isArray(selection) ||
+            Object.keys(selection).some(key => !['path', 'sha256'].includes(key)) ||
+            typeof selection.path !== 'string' ||
+            !isAbsolute(selection.path) ||
+            selection.path.length > 4096 ||
+            /[\0\r\n]/.test(selection.path) ||
+            typeof selection.sha256 !== 'string' ||
+            !/^[a-f0-9]{64}$/.test(selection.sha256)))
         throw new Error('Invalid plugin catalog selection');
     const plugins = {};
     for (const [name, value] of Object.entries(input.plugins)) {
@@ -24,15 +39,30 @@ export function validateOfficialPluginCatalog(value) {
             throw new Error('Invalid managed plugin declaration');
         const item = value;
         if (Object.keys(item).some(key => !['description', 'installArgs', 'setup', 'skill'].includes(key)) ||
-            typeof item.description !== 'string' || item.description.length > 1000 ||
-            typeof item.skill !== 'string' || !/^[a-z][a-z0-9-]*$/.test(item.skill) ||
-            !Array.isArray(item.installArgs) || item.installArgs.length === 0 || item.installArgs.length > 32 ||
+            typeof item.description !== 'string' ||
+            item.description.length > 1000 ||
+            typeof item.skill !== 'string' ||
+            !/^[a-z][a-z0-9-]*$/.test(item.skill) ||
+            !Array.isArray(item.installArgs) ||
+            item.installArgs.length === 0 ||
+            item.installArgs.length > 32 ||
             item.installArgs.some(arg => typeof arg !== 'string' || arg.length > 2048 || /[\0\r\n]/.test(arg)) ||
-            (item.setup !== undefined && (typeof item.setup !== 'string' || !/^[a-z][a-z0-9-]*$/.test(item.setup))))
+            (item.setup !== undefined &&
+                (typeof item.setup !== 'string' || !/^[a-z][a-z0-9-]*$/.test(item.setup))))
             throw new Error('Invalid managed plugin declaration');
-        plugins[name] = { description: item.description, skill: item.skill, installArgs: [...item.installArgs], ...(item.setup !== undefined && { setup: item.setup }) };
+        plugins[name] = {
+            description: item.description,
+            skill: item.skill,
+            installArgs: [...item.installArgs],
+            ...(item.setup !== undefined && { setup: item.setup }),
+        };
     }
-    const catalog = { schemaVersion: 1, revision: input.revision, plugins, ...(selection ? { selection: { path: selection.path, sha256: selection.sha256 } } : {}) };
+    const catalog = {
+        schemaVersion: 1,
+        revision: input.revision,
+        plugins,
+        ...(selection ? { selection: { path: selection.path, sha256: selection.sha256 } } : {}),
+    };
     if (Buffer.byteLength(JSON.stringify(catalog)) > MAX_CATALOG_BYTES)
         throw new Error('Managed plugin catalog exceeds 256 KiB');
     return catalog;
@@ -55,7 +85,8 @@ function selectionMatches(selection) {
                     break;
                 size += count;
             }
-            return size === stat.size && createHash('sha256').update(bytes.subarray(0, size)).digest('hex') === selection.sha256;
+            return (size === stat.size &&
+                createHash('sha256').update(bytes.subarray(0, size)).digest('hex') === selection.sha256);
         }
         finally {
             closeSync(fd);
@@ -84,7 +115,12 @@ export function readOfficialPluginCatalog() {
 }
 /** Installation hosts persist only the catalog selected by an approved preset. */
 export function replaceOfficialPluginCatalog(revision, plugins, selection) {
-    const catalog = validateOfficialPluginCatalog({ schemaVersion: 1, revision, plugins, ...(selection ? { selection } : {}) });
+    const catalog = validateOfficialPluginCatalog({
+        schemaVersion: 1,
+        revision,
+        plugins,
+        ...(selection ? { selection } : {}),
+    });
     const content = JSON.stringify(catalog);
     if (Buffer.byteLength(content) > MAX_CATALOG_BYTES)
         throw new Error('Managed plugin catalog exceeds 256 KiB');
@@ -109,17 +145,33 @@ function refreshOfficialPlugins() {
     try {
         plugins = readOfficialPluginCatalog()?.plugins ?? {};
     }
-    catch { /* An invalid optional catalog cannot disable registered plugin or browser commands. */ }
+    catch {
+        /* An invalid optional catalog cannot disable registered plugin or browser commands. */
+    }
     for (const name of Object.keys(OFFICIAL_PLUGINS))
         delete OFFICIAL_PLUGINS[name];
     Object.assign(OFFICIAL_PLUGINS, plugins);
     return OFFICIAL_PLUGINS;
 }
+/** Remove only registrations owned by the catalog for the exact active selection. */
+export function uninstallOfficialPluginCatalog(selection) {
+    const catalog = readOfficialPluginCatalog();
+    if (catalog?.selection?.path !== selection.path || catalog.selection.sha256 !== selection.sha256)
+        return;
+    for (const name of Object.keys(catalog.plugins)) {
+        if (findPluginRegistration(name)?.managedBy === OFFICIAL_PLUGIN_MANAGER)
+            unregisterPlugin(name);
+    }
+    rmSync(catalogPath(), { force: true });
+    refreshOfficialPlugins();
+}
 refreshOfficialPlugins();
 export function findOfficialPlugin(name) {
     const plugins = refreshOfficialPlugins();
     return Object.hasOwn(plugins, name) ? plugins[name] : undefined;
 }
 export function listOfficialPluginNames(setup) {
-    return Object.entries(refreshOfficialPlugins()).filter(([, item]) => setup === undefined || item.setup === setup).map(([name]) => name);
+    return Object.entries(refreshOfficialPlugins())
+        .filter(([, item]) => setup === undefined || item.setup === setup)
+        .map(([name]) => name);
 }

package/dist/plugins/sdk/plugin.d.ts

@@ -4,7 +4,7 @@ import type { PluginStateDeclaration } from '@mearl/browser-core';
 import type { PluginModelRequest, PluginModelResult } from '@mearl/browser-core';
 import type { PluginPageRuntime } from '@mearl/browser-core';
 import type { AppProfileContribution } from '@mearl/browser-core';
-export type { AppProfileContribution, AppProfileDefinition, } from '@mearl/browser-core';
+export type { AppProfileContribution, AppProfileDefinition } from '@mearl/browser-core';
 export { invokePageEvalWithArgs } from '../../pageEvalArguments.js';
 import { type OfficialPluginInstaller } from '../officialPluginInstaller.js';
 import { type PluginToolboxContribution, type PluginRegistration } from '../pluginRegistry.js';
@@ -16,7 +16,7 @@ export { PluginTaskClient } from '../clients/pluginTasks.js';
 export { cleanupPluginRuntime } from '../runtime/pluginRuntimeCleanup.js';
 export { PluginPageClient } from '../clients/pluginPages.js';
 export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, pluginRegistrationNeedsRefresh, listPluginNames, pluginDirectory, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, readPluginPageBundleChunk, type PluginRegistration, type PluginRegistrationOptions, type PluginToolboxAgentConfig, type PluginPageBundleRegistration, type PluginToolboxContribution, type PluginToolboxLocale, type PluginToolboxSandboxPage, } from '../pluginRegistry.js';
-export { findOfficialPlugin, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, OFFICIAL_PLUGINS, readOfficialPluginCatalog, replaceOfficialPluginCatalog, validateOfficialPluginCatalog, type PluginCatalogSelection, type PluginCatalog, type OfficialPluginDefinition, type OfficialPluginName, } from '../officialPluginCatalog.js';
+export { findOfficialPlugin, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, OFFICIAL_PLUGINS, readOfficialPluginCatalog, replaceOfficialPluginCatalog, uninstallOfficialPluginCatalog, validateOfficialPluginCatalog, type PluginCatalogSelection, type PluginCatalog, type OfficialPluginDefinition, type OfficialPluginName, } from '../officialPluginCatalog.js';
 export type PluginOptions = UnifiedInvokeOptions;
 export interface StructuredPluginProgress {
     message: string;

package/dist/plugins/sdk/plugin.js

@@ -19,7 +19,7 @@ export { PluginTaskClient } from '../clients/pluginTasks.js';
 export { cleanupPluginRuntime } from '../runtime/pluginRuntimeCleanup.js';
 export { PluginPageClient } from '../clients/pluginPages.js';
 export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, pluginRegistrationNeedsRefresh, listPluginNames, pluginDirectory, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, readPluginPageBundleChunk, } from '../pluginRegistry.js';
-export { findOfficialPlugin, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, OFFICIAL_PLUGINS, readOfficialPluginCatalog, replaceOfficialPluginCatalog, validateOfficialPluginCatalog, } from '../officialPluginCatalog.js';
+export { findOfficialPlugin, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, OFFICIAL_PLUGINS, readOfficialPluginCatalog, replaceOfficialPluginCatalog, uninstallOfficialPluginCatalog, validateOfficialPluginCatalog, } from '../officialPluginCatalog.js';
 function readPluginVersion(entry) {
     try {
         return readInstalledSkillMetadata(resolve(dirname(entry), '..'))?.version;
@@ -334,7 +334,10 @@ export async function loadPlugin(entry, context, pluginName) {
         }
         if (commands.size === 0 && !appProfiles)
             throw new Error('入口未注册任何命令');
-        if (defaultCommand !== undefined && (!commands.has(defaultCommand) || commands.get(defaultCommand)?.toolboxOnly || commands.get(defaultCommand)?.runtimeOnly))
+        if (defaultCommand !== undefined &&
+            (!commands.has(defaultCommand) ||
+                commands.get(defaultCommand)?.toolboxOnly ||
+                commands.get(defaultCommand)?.runtimeOnly))
             throw new Error('defaultCommand 必须指向公开命令');
         for (const command of Object.keys(taskRecovery?.commands ?? {})) {
             if (!commands.has(command) ||
@@ -411,13 +414,16 @@ export async function loadPlugin(entry, context, pluginName) {
         if (payload !== undefined && Object.keys(namedInput).length > 0) {
             throw new PluginError('PLUGIN_INVALID_INPUT', '插件业务选项与 --payload 调用不能混用');
         }
-        const defaultPayload = defaultCommand && toolboxPage === false && isObject(payload) && !Object.hasOwn(payload, 'command');
+        const defaultPayload = defaultCommand &&
+            toolboxPage === false &&
+            isObject(payload) &&
+            !Object.hasOwn(payload, 'command');
         if (payload !== undefined && !defaultPayload && !isPluginInvocation(payload)) {
             throw new PluginError('PLUGIN_INVALID_INPUT', '--payload 必须为 {"command":"...","input":{...}}');
         }
         const envelope = (defaultPayload ? { command: defaultCommand, input: payload } : payload);
         const positionalOffset = defaultCommand && !commands.has(positionals[0]) && toolboxPage === false ? 0 : 1;
-        const commandName = envelope?.command ?? (positionalOffset === 0 ? defaultCommand : positionals[0] ?? '');
+        const commandName = envelope?.command ?? (positionalOffset === 0 ? defaultCommand : (positionals[0] ?? ''));
         const hidden = toolboxPage === 'recovery' || toolboxPage === 'migration';
         const selected = find(commandName, hidden ? false : toolboxPage);
         const command = selected.command;
@@ -437,7 +443,9 @@ export async function loadPlugin(entry, context, pluginName) {
             : Object.fromEntries(command.registeredArguments
                 .map((argument, index) => [
                 argument.name(),
-                argument.variadic ? positionals.slice(index + positionalOffset) : positionals[index + positionalOffset],
+                argument.variadic
+                    ? positionals.slice(index + positionalOffset)
+                    : positionals[index + positionalOffset],
             ])
                 .filter(([, value]) => value !== undefined));
         for (const name of Object.keys(namedInput)) {
@@ -555,7 +563,9 @@ export async function loadPlugin(entry, context, pluginName) {
                 .join('\n');
         },
         help(namespace, name) {
-            const selected = name ? [find(defaultCommand && !commands.has(name) ? defaultCommand : name)] : publicCommands();
+            const selected = name
+                ? [find(defaultCommand && !commands.has(name) ? defaultCommand : name)]
+                : publicCommands();
             if (!selected.length) {
                 const location = toolbox
                     ? `请在 Mearl ${toolbox.displayMode === 'popup' ? 'Popup' : '工具箱'} 中打开「${toolbox.title}」使用。`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -68,11 +68,11 @@
     "commander": "^14.0.3",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/daemon-core": "3.0.0",
-    "@mearl/cloud-types": "3.0.0",
-    "@mearl/browser-core": "3.0.0",
-    "@mearl/agent-runtime": "3.0.0",
-    "@mearl/provider": "3.0.0"
+    "@mearl/daemon-core": "3.0.2",
+    "@mearl/cloud-types": "3.0.2",
+    "@mearl/agent-runtime": "3.0.2",
+    "@mearl/provider": "3.0.2",
+    "@mearl/browser-core": "3.0.2"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",

package/dist/pluginCliOutput.d.ts

@@ -1,2 +0,0 @@
-/** CLI host commands share the SDK error code without exporting arbitrary error metadata. */
-export declare function writePluginCliError(error: unknown): void;

package/dist/pluginCliOutput.js

@@ -1,7 +0,0 @@
-/** CLI host commands share the SDK error code without exporting arbitrary error metadata. */
-export function writePluginCliError(error) {
-    const code = error && typeof error === 'object' && 'code' in error && typeof error.code === 'string'
-        ? error.code
-        : 'PLUGIN_HOST_ERROR';
-    process.stderr.write(`${JSON.stringify({ error: { code, message: error instanceof Error ? error.message : String(error) } })}\n`);
-}