@mearl/setup 2.12.0 → 2.13.0

package/README.md

@@ -9,6 +9,7 @@ npx @mearl/setup extension [--full] [--force]
 npx @mearl/setup plugin <name> <path>
 npx @mearl/setup plugin install <ali-skills add 参数...>
 npx @mearl/setup plugin uninstall <name>
+npx @mearl/setup provider <install|update|uninstall> <package|id>
 ```
 
 配置 AgentBay API Key 时只需执行一次下面的命令，然后在隐藏输入提示中粘贴 Key。
@@ -70,6 +71,23 @@ npx @mearl/setup plugin uninstall yuque
 移除失败时保留注册以便重试。手工注册的其他路径只解除 Mearl 注册，不删除源码。
 重复卸载未注册名称会成功返回，不产生改动。
 
+## 管理浏览器 Provider
+
+Provider 由 npm 包分发，但包本身无需暴露 CLI 或安装脚本。setup 使用当前 npm 包管理器
+完成全局包生命周期，再读取包内的 `package.json#mearl.provider` 元数据登记协议入口、
+可创建的浏览器类型名称及其表单参数：
+
+```bash
+npx @mearl/setup provider install @ali/mearl-provider-brow
+npx @mearl/setup provider update brow
+npx @mearl/setup provider uninstall brow
+```
+
+安装参数接受包名、版本或 dist-tag；更新和卸载可使用 `providerId` 或完整包名。阿里包在
+本机存在 `tnpm` 时优先使用 `tnpm`，其他情况沿用启动 setup 的包管理器。Provider 登记只保存
+经过校验的包名、安装目录和包内入口；不接受包自行注入启动命令、参数、工作目录或环境变量。
+卸载仅在包管理器成功移除包后清除登记，以便失败时可以重试。
+
 ## 行为
 
 - `install` 可以省略；直接执行 `npx @mearl/setup` 等同于 `npx @mearl/setup install`。
@@ -200,4 +218,4 @@ npx @mearl/setup agentbay
 npx @mearl/setup agentbay --key-file ./agentbay.key
 ```
 
-原有的 npm/npx 安装方式和各包 CLI 保持可用；setup 只是统一的便利入口。
+原有 Mearl 环境包的 npm/npx 安装方式和 CLI 保持可用；setup 是统一的便利入口。

package/dist/cli.d.ts

@@ -4,6 +4,7 @@ import { installMearlBrowserExtension } from './browserExtension.js';
 import { runMearlLifecycle, type MearlLifecycleOperation } from './lifecycle.js';
 import type { MearlProfile } from './profiles.js';
 import { installPlugins, setupPlugin, uninstallPlugin } from './plugin.js';
+import { installProviderPackage, uninstallProviderPackage, updateProviderPackage } from './provider.js';
 export declare const SETUP_VERSION: string;
 interface ParsedArgs {
     agentBayKeyFile?: string;
@@ -12,11 +13,13 @@ interface ParsedArgs {
     force?: boolean;
     full?: boolean;
     help: boolean;
-    operation?: MearlLifecycleOperation | 'agentbay' | 'extension' | 'plugin';
+    operation?: MearlLifecycleOperation | 'agentbay' | 'extension' | 'plugin' | 'provider';
     pluginName?: string;
     pluginPath?: string;
     pluginInstallArgs?: string[];
     pluginUninstallName?: string;
+    providerCommand?: 'install' | 'uninstall' | 'update';
+    providerTarget?: string;
     profiles?: MearlProfile[];
     skipSkill: boolean;
     targetLine?: string;
@@ -32,7 +35,10 @@ export interface SetupCliDependencies {
     readAgentBayKeyFile?: typeof readAgentBayApiKeyFile;
     readAgentBayKeyStdin?: typeof readAgentBayApiKeyStdin;
     installBrowserExtension?: typeof installMearlBrowserExtension;
+    installProvider?: typeof installProviderPackage;
     runLifecycle?: typeof runMearlLifecycle;
+    uninstallProvider?: typeof uninstallProviderPackage;
+    updateProvider?: typeof updateProviderPackage;
 }
 export declare function parseSetupArgs(argv: string[]): ParsedArgs;
 export declare function main(argv?: string[], interactiveTerminal?: boolean, dependencies?: SetupCliDependencies): Promise<number>;

package/dist/cli.js

@@ -6,6 +6,7 @@ import { installMearlBrowserExtension } from './browserExtension.js';
 import { runMearlLifecycle } from './lifecycle.js';
 import { isMearlReleaseLine } from './version.js';
 import { installPlugins, setupPlugin, uninstallPlugin } from './plugin.js';
+import { installProviderPackage, uninstallProviderPackage, updateProviderPackage, } from './provider.js';
 const require = createRequire(import.meta.url);
 export const SETUP_VERSION = require('../package.json').version;
 const baseParsedArgs = () => ({
@@ -25,6 +26,20 @@ function commanderError(error) {
     return new Error(message);
 }
 export function parseSetupArgs(argv) {
+    if (argv[0] === 'provider') {
+        const command = argv[1];
+        if ((command === 'install' || command === 'update' || command === 'uninstall') &&
+            argv.length === 3 &&
+            argv[2]) {
+            return {
+                ...baseParsedArgs(),
+                operation: 'provider',
+                providerCommand: command,
+                providerTarget: argv[2],
+            };
+        }
+        throw new Error('provider requires install <package>, update <id>, or uninstall <id>');
+    }
     if (argv[0] === 'plugin' && argv[1] === 'install') {
         return { ...baseParsedArgs(), operation: 'plugin', pluginInstallArgs: argv.slice(2) };
     }
@@ -166,6 +181,7 @@ Usage:
   npx @mearl/setup plugin <name> <path>
   npx @mearl/setup plugin install <ali-skills add arguments...>
   npx @mearl/setup plugin uninstall <name>
+  npx @mearl/setup provider <install|update|uninstall> <package|id>
   npx @mearl/setup agentbay [--stdin | --key-file <path>]
 
 Behavior:
@@ -175,6 +191,7 @@ Behavior:
   extension    Install or update the browser extension; --full also installs the local environment
   agentbay     Save or update AGENTBAY_KEY without changing other Mearl settings
   plugin       Register, install, or uninstall a CLI plugin
+  provider     Install npm Provider packages and manage their Mearl registration
 
 Options:
   --local      Manage @mearl/native-host and @mearl/client
@@ -206,6 +223,7 @@ Examples:
   npx @mearl/setup extension
   npx @mearl/setup extension --full
   npx @mearl/setup plugin uninstall yuque
+  npx @mearl/setup provider install @ali/mearl-provider-brow
   npx @mearl/setup agentbay
   npx @mearl/setup --qoder-cloud --yes
   npx @mearl/setup update --local --target-line 2.3.x --skip-skill
@@ -268,6 +286,27 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
             return 1;
         }
     }
+    if (parsed.operation === 'provider') {
+        try {
+            const target = parsed.providerTarget;
+            const result = parsed.providerCommand === 'install'
+                ? await (dependencies.installProvider ?? installProviderPackage)(target)
+                : parsed.providerCommand === 'update'
+                    ? await (dependencies.updateProvider ?? updateProviderPackage)(target)
+                    : await (dependencies.uninstallProvider ?? uninstallProviderPackage)(target);
+            const verb = parsed.providerCommand === 'uninstall'
+                ? 'uninstalled'
+                : parsed.providerCommand === 'update'
+                    ? 'updated'
+                    : 'installed';
+            console.error(`Provider ${result.manifest.providerId} ${verb}: ${result.manifest.packageName}@${result.manifest.version} (${result.manager})`);
+            return 0;
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            return 1;
+        }
+    }
     if (parsed.operation === 'agentbay') {
         try {
             const configureAgentBay = dependencies.configureAgentBay ?? configureAgentBayApiKey;

package/dist/index.d.ts

@@ -11,4 +11,6 @@ export type { DetectedMearlProfiles, MearlProfile, MearlProfileConfig } from './
 export { MEARL_NATIVE_HOST_NAMES, resolveNativeHostDirectory, uninstallNativeHostArtifacts, } from './nativeHost.js';
 export { compareMearlReleaseLines, compareMearlReleaseVersions, isMearlReleaseLine, isMearlReleaseVersion, isMearlReleaseVersionInLine, mearlReleaseLineForVersion, parseMearlReleaseLine, parseMearlReleaseVersion, } from './version.js';
 export type { MearlReleaseLine, MearlReleaseVersion } from './version.js';
+export { installProviderPackage, parseProviderPackageSpec, uninstallProviderPackage, updateProviderPackage, } from './provider.js';
+export type { ProviderSetupDependencies, ProviderSetupResult } from './provider.js';
 export type { NativeHostCleanupDependencies, NativeHostCleanupOptions, NativeHostIntegrationMode, } from './nativeHost.js';

package/dist/index.js

@@ -5,3 +5,4 @@ export { runMearlLifecycle } from './lifecycle.js';
 export { MEARL_PROFILES, detectMearlProfiles } from './profiles.js';
 export { MEARL_NATIVE_HOST_NAMES, resolveNativeHostDirectory, uninstallNativeHostArtifacts, } from './nativeHost.js';
 export { compareMearlReleaseLines, compareMearlReleaseVersions, isMearlReleaseLine, isMearlReleaseVersion, isMearlReleaseVersionInLine, mearlReleaseLineForVersion, parseMearlReleaseLine, parseMearlReleaseVersion, } from './version.js';
+export { installProviderPackage, parseProviderPackageSpec, uninstallProviderPackage, updateProviderPackage, } from './provider.js';

package/dist/plugin.js

@@ -17,9 +17,9 @@ const registrationContext = {
 export async function setupPlugin(name, target) {
     assertPluginName(name);
     const entry = resolvePluginEntry(target);
-    await loadPlugin(entry, registrationContext);
+    const plugin = await loadPlugin(entry, registrationContext);
     await ensurePluginRuntime();
-    return registerPlugin(name, entry);
+    return registerPlugin(name, entry, plugin.description);
 }
 function globalAliSkill(entry) {
     const globalSkillsDirectory = join(homedir(), '.agents', 'skills');
@@ -170,15 +170,15 @@ export async function installPlugins(args, runner = runCommand) {
         assertPluginName(name);
         if (plugins.has(name))
             throw new Error(`多个 skill 使用插件名称 ${name}，请通过 setup plugin <name> <path> 分别注册。`);
-        plugins.set(name, entry);
+        plugins.set(name, { entry, description: plugin.description });
     }
     if (plugins.size === 0) {
         console.error('未找到 scripts/main.mjs 插件入口；自定义入口可用 setup plugin <name> <path> 注册。');
         return 0;
     }
     await ensurePluginRuntime(runner);
-    for (const [name, entry] of plugins) {
-        registerPlugin(name, entry);
+    for (const [name, { entry, description }] of plugins) {
+        registerPlugin(name, entry, description);
         console.error(`Plugin ${name} registered: ${entry}\nRun: mearl ${name} --help`);
     }
     return 0;

package/dist/provider.d.ts

@@ -0,0 +1,28 @@
+import { listInstalledProviders, registerProviderPackage, stopProvider, uninstallProvider, type InstalledProviderManifest } from '@mearl/provider/host';
+import { resolvePackageManagerInstallation, type PackageManagerInstallation } from './packageManager.js';
+import { findExecutable, type CommandRunner } from './process.js';
+interface ProviderPackageSpec {
+    packageName: string;
+    target: string;
+}
+export interface ProviderSetupDependencies {
+    existsSync?: (filePath: string) => boolean;
+    findExecutable?: typeof findExecutable;
+    listProviders?: typeof listInstalledProviders;
+    registerPackage?: typeof registerProviderPackage;
+    resolveInvokingManager?: (env: NodeJS.ProcessEnv) => PackageManagerInstallation;
+    resolvePackageManager?: typeof resolvePackageManagerInstallation;
+    resolvePackageRoot?: (installation: PackageManagerInstallation, packageName: string, runner: CommandRunner, env: NodeJS.ProcessEnv) => Promise<string>;
+    runCommand?: CommandRunner;
+    stopProvider?: typeof stopProvider;
+    unregisterProvider?: typeof uninstallProvider;
+}
+export interface ProviderSetupResult {
+    manifest: InstalledProviderManifest;
+    manager: PackageManagerInstallation['manager'];
+}
+export declare function parseProviderPackageSpec(value: string): ProviderPackageSpec;
+export declare function installProviderPackage(packageSpec: string, dependencies?: ProviderSetupDependencies): Promise<ProviderSetupResult>;
+export declare function updateProviderPackage(selector: string, dependencies?: ProviderSetupDependencies): Promise<ProviderSetupResult>;
+export declare function uninstallProviderPackage(selector: string, dependencies?: ProviderSetupDependencies): Promise<ProviderSetupResult>;
+export {};

package/dist/provider.js

@@ -0,0 +1,114 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { listInstalledProviders, registerProviderPackage, stopProvider, uninstallProvider, } from '@mearl/provider/host';
+import { buildGlobalPackageCommand, resolveInvokingPackageManager, resolvePackageManagerInstallation, } from './packageManager.js';
+import { findExecutable, prependCommandPath, runCommand } from './process.js';
+export function parseProviderPackageSpec(value) {
+    const input = value.trim();
+    const nameMatch = input.match(/^(@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._-]*)(?:@(.+))?$/i);
+    if (!nameMatch || !nameMatch[1] || /\s/.test(nameMatch[2] ?? '')) {
+        throw new Error(`Provider install requires an npm package name, received: ${value}`);
+    }
+    return { packageName: nameMatch[1], target: nameMatch[2] || 'latest' };
+}
+function providerManager(packageName, env, dependencies) {
+    const resolved = (dependencies.resolveInvokingManager ??
+        (childEnv => resolveInvokingPackageManager({ env: childEnv })))(env);
+    if (!packageName.startsWith('@ali/') || resolved.command.includes('tnpm'))
+        return resolved;
+    const tnpm = (dependencies.findExecutable ?? findExecutable)('tnpm', {
+        env,
+        extraDirectories: [dirname(process.execPath)],
+    });
+    return tnpm ? { manager: 'npm', command: tnpm } : resolved;
+}
+function outputPath(output) {
+    const lines = output
+        .split(/\r?\n/)
+        .map(line => line.trim())
+        .filter(Boolean);
+    return lines.at(-1) ?? null;
+}
+async function resolveGlobalProviderPackageRoot(installation, packageName, runner, env) {
+    let args;
+    let toNodeModules;
+    switch (installation.manager) {
+        case 'npm':
+        case 'pnpm':
+            args = ['root', '-g'];
+            toNodeModules = value => value;
+            break;
+        case 'yarn':
+            args = ['global', 'dir'];
+            toNodeModules = value => join(value, 'node_modules');
+            break;
+        case 'bun':
+            args = ['pm', 'bin', '-g'];
+            toNodeModules = value => resolve(value, '..', 'install', 'global', 'node_modules');
+            break;
+        case 'volta':
+            throw new Error('Volta cannot manage a Provider package without a binary; use npm or pnpm');
+    }
+    const result = await runner(installation.command, args, {
+        capture: true,
+        env: prependCommandPath(installation.command, env),
+    });
+    const root = outputPath(result.stdout);
+    if (result.code !== 0 || !root) {
+        throw new Error(`${installation.manager} global package root lookup failed`);
+    }
+    return join(toNodeModules(root), ...packageName.split('/'));
+}
+function findRegisteredProvider(selector, listProviders) {
+    const providers = listProviders();
+    const matches = providers.filter(provider => provider.providerId === selector || provider.packageName === selector);
+    if (matches.length === 0)
+        throw new Error(`Provider is not registered: ${selector}`);
+    if (matches.length > 1)
+        throw new Error(`Provider selector is ambiguous: ${selector}`);
+    return matches[0];
+}
+async function runPackageCommand(installation, operation, packageName, target, runner, env) {
+    const command = buildGlobalPackageCommand(installation, operation, [packageName], target);
+    const result = await runner(command.command, command.args, {
+        env: prependCommandPath(command.command, env),
+        tee: true,
+    });
+    if (result.code !== 0) {
+        throw new Error(`${packageName} ${operation} failed (exit ${result.code})`);
+    }
+}
+export async function installProviderPackage(packageSpec, dependencies = {}) {
+    const { packageName, target } = parseProviderPackageSpec(packageSpec);
+    const env = process.env;
+    const runner = dependencies.runCommand ?? runCommand;
+    const installation = providerManager(packageName, env, dependencies);
+    await runPackageCommand(installation, 'install', packageName, target, runner, env);
+    const packageRoot = await (dependencies.resolvePackageRoot ?? resolveGlobalProviderPackageRoot)(installation, packageName, runner, env);
+    if (!(dependencies.existsSync ?? existsSync)(join(packageRoot, 'package.json'))) {
+        throw new Error(`${packageName} was installed but its package root was not found: ${packageRoot}`);
+    }
+    const manifest = (dependencies.registerPackage ?? registerProviderPackage)(packageRoot);
+    return { manifest, manager: installation.manager };
+}
+export async function updateProviderPackage(selector, dependencies = {}) {
+    const listProviders = dependencies.listProviders ?? listInstalledProviders;
+    const current = findRegisteredProvider(selector, listProviders);
+    const env = process.env;
+    const runner = dependencies.runCommand ?? runCommand;
+    const installation = (dependencies.resolvePackageManager ?? resolvePackageManagerInstallation)(current.packageRoot, current.packageName) ?? providerManager(current.packageName, env, dependencies);
+    (dependencies.stopProvider ?? stopProvider)(current.providerId);
+    await runPackageCommand(installation, 'update', current.packageName, 'latest', runner, env);
+    const manifest = (dependencies.registerPackage ?? registerProviderPackage)(current.packageRoot);
+    return { manifest, manager: installation.manager };
+}
+export async function uninstallProviderPackage(selector, dependencies = {}) {
+    const listProviders = dependencies.listProviders ?? listInstalledProviders;
+    const manifest = findRegisteredProvider(selector, listProviders);
+    const env = process.env;
+    const installation = (dependencies.resolvePackageManager ?? resolvePackageManagerInstallation)(manifest.packageRoot, manifest.packageName) ?? providerManager(manifest.packageName, env, dependencies);
+    (dependencies.stopProvider ?? stopProvider)(manifest.providerId);
+    await runPackageCommand(installation, 'uninstall', manifest.packageName, 'latest', dependencies.runCommand ?? runCommand, env);
+    (dependencies.unregisterProvider ?? uninstallProvider)(manifest.providerId);
+    return { manifest, manager: installation.manager };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",
@@ -65,7 +65,8 @@
     "commander": "^15.0.0",
     "extract-zip": "^2.0.1",
     "ws": "^8.18.3",
-    "@mearl/client": "2.12.0"
+    "@mearl/client": "2.13.0",
+    "@mearl/provider": "2.13.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",