@mearl/setup 3.0.0-beta.4 → 3.0.0-beta.5

package/README.md

@@ -5,20 +5,20 @@
 Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全局安装 setup：
 
 ```bash
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta [install] [--local] [--cloud|--qoder-cloud] [--mcp]
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta update [--local] [--cloud|--qoder-cloud] [--mcp]
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta uninstall [--local] [--cloud|--qoder-cloud] [--mcp] [--full]
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta extension [--full] [--force]
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta plugin [name] <path>
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta plugin install <skills add 参数...>
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta plugin uninstall <name>
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta provider <install|update|uninstall> <package|id>
+npx @mearl/setup@beta [install] [--local] [--cloud|--qoder-cloud] [--mcp]
+npx @mearl/setup@beta update [--local] [--cloud|--qoder-cloud] [--mcp]
+npx @mearl/setup@beta uninstall [--local] [--cloud|--qoder-cloud] [--mcp] [--full]
+npx @mearl/setup@beta extension [--full] [--force]
+npx @mearl/setup@beta plugin [name] <path>
+npx @mearl/setup@beta plugin install <skills add 参数...>
+npx @mearl/setup@beta plugin uninstall <name>
+npx @mearl/setup@beta provider <install|update|uninstall> <package|id>
 ```
 
 浏览器 Provider 独立安装和演进。安装后运行 `mearl <providerId>` 查看该版本声明的能力、
 配置和启动参数。
 
-在 Qoder Cloud Agent 环境中，使用 `npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta --qoder-cloud --yes` 选择 Qoder
+在 Qoder Cloud Agent 环境中，使用 `npx @mearl/setup@beta --qoder-cloud --yes` 选择 Qoder
 配对模式。它与 `--cloud` 安装同一套 cloud-server、client 和 Skill，只把 cloud-server
 模式记录为 Qoder；`mearl-cloud-server` 的命令交互保持不变，`start` 和 `restart` 输出新的
 配对指令后退出，不监听端口或保留守护进程。配对 URL 不包含 Qoder PAT。
@@ -28,7 +28,7 @@ npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta provider <ins
 一个命令安装 skill 并注册它的 CLI、SDK 和 MCP 能力：
 
 ```bash
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta plugin install https://github.com/F-loat/mearl/tree/v3.0.0-beta.1 --skill browser-tab-manager --yes
+npx @mearl/setup@beta plugin install https://github.com/F-loat/mearl/tree/v3.0.0-beta.1 --skill browser-tab-manager --yes
 mearl tabs summary
 ```
 
@@ -45,8 +45,8 @@ Native preset 批次新建的插件注册使用 setup 托管归属，后续通
 已通过其他渠道分发的 skill 或自定义入口，可以直接传入路径注册：
 
 ```bash
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta plugin /absolute/path/to/browser-tab-manager
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta plugin custom ./skills/custom/entry.mjs
+npx @mearl/setup@beta plugin /absolute/path/to/browser-tab-manager
+npx @mearl/setup@beta plugin custom ./skills/custom/entry.mjs
 ```
 
 path 接受目录或具体文件；目录默认读取 `scripts/main.mjs` 或 `scripts/main.py`，相对路径基于调用工作目录解析。插件名优先使用显式 name，其次读取入口的 `name` metadata，最后回退到 Skill 目录名；常规注册只传 path，显式 name 仅用于覆盖或兼容旧入口。Python 插件要求 `python3 >= 3.9`，可通过 `MEARL_PYTHON` 指定解释器路径；setup 只验证入口可加载，不安装 Python，也不执行 `pip install`。
@@ -59,7 +59,7 @@ native-host 会幂等初始化 Skills 模式。基础环境补齐或初始化失
 不再需要插件时执行：
 
 ```bash
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta plugin uninstall tabs
+npx @mearl/setup@beta plugin uninstall tabs
 ```
 
 若入口位于 `~/.agents/skills/<skill>/`，setup 会先执行
@@ -75,9 +75,9 @@ Provider 由 npm 包分发，但包本身无需暴露 CLI 或安装脚本。setu
 可创建的浏览器类型名称及其表单参数：
 
 ```bash
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta provider install @example/mearl-provider-device
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta provider update example-device
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta provider uninstall example-device
+npx @mearl/setup@beta provider install @example/mearl-provider-device
+npx @mearl/setup@beta provider update example-device
+npx @mearl/setup@beta provider uninstall example-device
 ```
 
 安装参数接受包名、版本或 dist-tag；更新和卸载可使用 providerId 或完整包名。核心 @mearl 包固定使用公共 npm registry；其余 scope 沿用调用方的包管理器配置，组织 registry 由能力安装引导提供。安装沿用启动 setup 的包管理器，
@@ -88,8 +88,8 @@ npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta provider unin
 ## 行为
 
 - Mearl 自有 npm 包的安装和更新固定使用 `https://registry.npmjs.org/`，与最新版本查询使用同一来源；第三方包沿用当前包管理器的源配置。
-- `install` 可以省略；直接执行 `npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta` 等同于 `npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta install`。
-  以选项开头时也默认安装，例如 `npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta --cloud --yes`。
+- `install` 可以省略；直接执行 `npx @mearl/setup@beta` 等同于 `npx @mearl/setup@beta install`。
+  以选项开头时也默认安装，例如 `npx @mearl/setup@beta --cloud --yes`。
 - `install` 未指定环境时默认 `--local`。
 - `-h` / `--help` 显示帮助，`-v` / `--version` 显示 setup 版本。
 - `update` 和 `uninstall` 未指定环境时，从当前 `PATH` 中的
@@ -137,19 +137,19 @@ npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta provider unin
 ## 安装或更新浏览器扩展
 
 ```bash
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta extension
+npx @mearl/setup@beta extension
 ```
 
 首次使用时可一次安装完整的本地浏览器环境：
 
 ```bash
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta extension --full
+npx @mearl/setup@beta extension --full
 ```
 
 首次安装、旧版 setup 扩展首次迁移，或 Native Host reload 不可用时才需要 CDP。如果
 Chrome 尚未开放 CDP，交互命令会提示打开
 `chrome://inspect/#remote-debugging`、启用远程调试并允许连接，然后等待安装完成。面向人的
-安装指引不要添加 `--yes`。无 TTY 环境使用 `npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta extension --yes`；它只尝试
+安装指引不要添加 `--yes`。无 TTY 环境使用 `npx @mearl/setup@beta extension --yes`；它只尝试
 一次，CDP 不可用时立即中断。无法确认 setup 管理来源且 CDP 不可用时不会下载或修改插件
 目录，打开 CDP 后重新执行同一命令即可。Chrome 版本过低、缺少扩展安装所需的 CDP 方法时，
 命令会中断并提示升级 Chrome。
@@ -179,7 +179,7 @@ DevTools 面板的设置按钮会显示红点，快捷设置中提供“立即
 
 自动更新不会降级较新的 Host，也不会改动 cloud、MCP 或独立安装的 Mearl Skill。
 目标 npm 版本尚未发布、网络不可用或更新失败时，旧 Host 会继续运行；下一次扩展后台
-生命周期可重新尝试，也可手动执行 `npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta update --local`。
+生命周期可重新尝试，也可手动执行 `npx @mearl/setup@beta update --local`。
 
 ## 人工与 Agent 使用
 
@@ -194,41 +194,41 @@ DevTools 面板的设置按钮会显示红点，快捷设置中提供“立即
 
 ```bash
 # 默认安装本地浏览器环境
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup
+npx @mearl/setup
 
 # 与上一条等价
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta install
+npx @mearl/setup@beta install
 
 # Agent / CI 无交互安装
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta --yes
+npx @mearl/setup@beta --yes
 
 # 安装云端 Agent 环境
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta --cloud
+npx @mearl/setup@beta --cloud
 
 # 同一台机器同时作为本地浏览器宿主和云端 Agent
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta --local --cloud
+npx @mearl/setup@beta --local --cloud
 
 # 自动更新当前 PATH 中检测到的全部 Mearl 环境
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta update
+npx @mearl/setup@beta update
 
 # 独立安装或更新到最新浏览器扩展
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta extension
+npx @mearl/setup@beta extension
 
 # 安装完整本地环境（client、Native Host、Skill 和扩展）
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta extension --full
+npx @mearl/setup@beta extension --full
 
 # 只卸载本地环境
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta uninstall --local
+npx @mearl/setup@beta uninstall --local
 
 # 自动检测并无交互卸载
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta uninstall --yes
+npx @mearl/setup@beta uninstall --yes
 
 # 卸载环境，并清理全部 CLI 插件与 Provider
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta uninstall --full
+npx @mearl/setup@beta uninstall --full
 
 # 安装可选浏览器 Provider
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta provider install @example/mearl-provider-device
-npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta provider install @example/mearl-provider-cloud
+npx @mearl/setup@beta provider install @example/mearl-provider-device
+npx @mearl/setup@beta provider install @example/mearl-provider-cloud
 ```
 
 原有 Mearl 环境包的 npm/npx 安装方式和 CLI 保持可用；setup 是统一的便利入口。
@@ -237,6 +237,12 @@ npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta provider inst
 
 `mearl-setup preset apply <source-url-or-path>` 准备确切资源、激活本机 Node 选择，并向兼容扩展同步同一批浏览器资源；`preset update` 保留用户覆盖，`preset status` 只读检查实际就绪状态。退出码 3 表示存在待同步/安装组件。完整扩展、默认设置、Skills/Provider 和网页一键安装使用同一实际状态核验，见 [本机安装合同](../../docs/preset-installation.md)。
 
-普通 install/update 在替换包前保存选中 preset 的确切资源和期望选择，运行时初始化后再同步宿主和安装 Skills；`extension --full` 也在替换扩展前完成准备。已有本机 preset 优先保留，显式 `--preset` 可更新或修复资源；检测到已安装包为 3.0 以前版本且尚无选择时，读取公共部署目录的 `legacyPreset`。配置或资源不可用会在包变更前停止，不回退到无内部能力的安装。部分升级后的重试使用已保存安装记录，即使包版本已变为 3.x 也不重新下载。维护旧版本线和卸载不自动迁移。
+普通 install/update 在替换包前保存选中 preset 的确切资源和期望选择，运行时初始化后再同步宿主和安装 Skills；`extension --full` 也在替换扩展前完成准备。已有本机 preset 优先保留，显式 `--preset` 可更新或修复资源。配置或资源不可用会在包变更前停止，不回退到无内部能力的安装。部分升级后的重试使用已保存安装记录，即使包版本已变为 3.x 也不重新下载。卸载不准备或安装 preset。
 
 默认目录为公共站点的 `installation.json`，可通过 `MEARL_INSTALLATION_CONFIG_URL` 指定其他 HTTPS 目录（本地验证允许回环 HTTP）。核心不包含组织 ID 或私有来源；目录沿用网页安装的校验合同。本机与浏览器未全部确认时仍报告 pending，准备成功不表示已发行或已完成真实企业授权验收。
+
+## 浏览器 preset 与发行入口
+
+主动执行 setup 时，先沿用本机已选 preset；本机未选择时，在运行时初始化后、安装 Skill 前采用已连接浏览器的受信 preset。显式 `--preset <source>` 优先。多个浏览器的选择不同、来源不受信或状态读取失败时要求显式选择。首次连接最多等待约一分钟；浏览器关闭时只安装基础环境并说明重试方式。普通连接和后台核心更新不会自动安装首次本机 preset。
+
+发行包可设置本机进程环境变量 `MEARL_SETUP_DEFAULT_PRESET` 提供默认清单来源；默认值仅在两端均无选择时生效，插件、Provider、卸载等子命令保持原行为。安装与状态核验仍由公共安装器负责。

package/dist/browserPreset.d.ts

@@ -0,0 +1,20 @@
+import { invokeLocalHost, listLiveBrowsers } from '@mearl/client/local';
+import { loadInstallationConfig } from '@mearl/preset/installation';
+import { createNodePresetLoader } from './preset.js';
+import type { StagedPresetInstallation } from './preset.js';
+interface Options {
+    env?: NodeJS.ProcessEnv;
+    waitMs?: number;
+    writeLine?: (line: string) => void;
+}
+interface Dependencies {
+    browsers?: typeof listLiveBrowsers;
+    invoke?: typeof invokeLocalHost;
+    configuration?: () => ReturnType<typeof loadInstallationConfig>;
+    load?: ReturnType<typeof createNodePresetLoader>;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Explicit setup may complete a trusted browser selection before installing any Skills. */
+export declare function prepareBrowserSetupPreset(options?: Options, dependencies?: Dependencies): Promise<StagedPresetInstallation | undefined>;
+export {};

package/dist/browserPreset.js

@@ -0,0 +1,82 @@
+import { invokeLocalHost, listLiveBrowsers } from '@mearl/client/local';
+import { installationOriginCovered, loadInstallationConfig, matchesInstallationOrigin, trustedInstallationPreset } from '@mearl/preset/installation';
+import { createNodePresetLoader, PresetInstaller, resolveInstallationConfigUrl } from './preset.js';
+/** Explicit setup may complete a trusted browser selection before installing any Skills. */
+export async function prepareBrowserSetupPreset(options = {}, dependencies = {}) {
+    const env = options.env ?? process.env;
+    const directory = env.MEARL_CAPABILITY_DIR;
+    const current = await new PresetInstaller({ directory }).store.current();
+    if (current.activation || current.receipt)
+        return;
+    const now = dependencies.now ?? Date.now;
+    const deadline = now() + (options.waitMs ?? 0);
+    const browsers = dependencies.browsers ?? listLiveBrowsers;
+    const invoke = dependencies.invoke ?? invokeLocalHost;
+    const sleep = dependencies.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+    const configuration = dependencies.configuration ?? (() => {
+        const url = resolveInstallationConfigUrl(env.MEARL_INSTALLATION_CONFIG_URL);
+        return loadInstallationConfig(url, url.origin, AbortSignal.timeout(5_000));
+    });
+    const read = async (timeoutSec = 5) => {
+        const targets = browsers().filter(browser => !browser.provider && browser.transport === 'extension' && browser.status === 'connected' && (!env.MEARL_SOCKET_PATH || browser.socketPath === env.MEARL_SOCKET_PATH));
+        if (!targets.length)
+            return;
+        return (await Promise.all(targets.map(async (browser) => {
+            let value;
+            try {
+                value = await invoke('preset_browser_status', {}, { socketPath: browser.socketPath, timeoutSec });
+            }
+            catch {
+                throw new Error(`Cannot read preset from ${browser.browserId}. Reconnect the extension and retry setup, or use --preset <source>.`);
+            }
+            if (value?.error || typeof value?.browserReady !== 'boolean' || !Object.hasOwn(value, 'browserRevision') || (value.presetId !== undefined && (typeof value.presetId !== 'string' || !value.presetId || typeof value.presetSource !== 'string' || typeof value.browserRevision !== 'string' || value.browserReady !== true)))
+                throw new Error(`Browser preset is unavailable in ${browser.browserId}. Reconnect the extension and retry setup, or use --preset <source>.`);
+            if (!value.presetId)
+                return [];
+            return [{ browserId: browser.browserId, presetId: value.presetId, presetSource: value.presetSource, browserRevision: value.browserRevision }];
+        }))).flat();
+    };
+    let selected = await read();
+    if (!selected && now() < deadline)
+        options.writeLine?.('Waiting for the Mearl extension to connect and checking its installed preset…');
+    while (!selected && now() < deadline) {
+        await sleep(Math.min(1000, deadline - now()));
+        if (now() < deadline)
+            selected = await read(Math.max(0.1, Math.min(5, (deadline - now()) / 1000)));
+    }
+    if (!selected) {
+        options.writeLine?.('No connected Mearl extension was found. Continuing without a browser preset; connect and rerun setup to adopt it, or use --preset <source> to select a preset.');
+        return;
+    }
+    if (!selected.length)
+        return;
+    const accepted = selected;
+    const first = accepted[0];
+    if (accepted.some(value => value.presetId !== first.presetId || value.presetSource !== first.presetSource))
+        throw new Error('Connected browsers use different presets. Select one explicitly with --preset <source>.');
+    const trusted = trustedInstallationPreset(await configuration(), first.presetId, first.presetSource);
+    if (!trusted)
+        throw new Error('The browser preset is not in the trusted installation catalog. Install it explicitly with --preset <source>.');
+    const load = dependencies.load ?? createNodePresetLoader();
+    const installer = new PresetInstaller({ directory, load: (source, resourceOptions) => {
+            const url = new URL(source);
+            if (url.protocol !== 'https:' || url.username || url.password || !trusted.origins.some(origin => matchesInstallationOrigin(origin, url)))
+                throw new Error('Browser preset resource is outside the trusted installation catalog');
+            return load(source, resourceOptions);
+        } });
+    options.writeLine?.(`Using the browser's trusted preset: ${first.presetId}`);
+    return installer.stage(first.presetSource, {
+        expectedId: first.presetId, expectedRevision: null, signal: AbortSignal.timeout(120_000),
+        validatePrepared: async (prepared) => {
+            if (prepared.preset.permissions.origins.some(origin => !installationOriginCovered(origin, trusted.origins)))
+                throw new Error('Browser preset permissions exceed the trusted installation catalog');
+        },
+        confirm: async () => {
+            if (JSON.stringify(trustedInstallationPreset(await configuration(), first.presetId, first.presetSource)) !== JSON.stringify(trusted))
+                throw new Error('Browser preset trust changed during setup');
+            const latest = await read();
+            if (!latest || latest.length !== accepted.length || accepted.some(value => !latest.some(other => value.browserId === other.browserId && value.presetId === other.presetId && value.presetSource === other.presetSource && value.browserRevision === other.browserRevision)))
+                throw new Error('The browser preset changed during setup. Retry or use --preset <source>.');
+        },
+    });
+}

package/dist/cli.d.ts

@@ -5,7 +5,7 @@ import type { MearlProfile } from './profiles.js';
 import { ensureOfficialPlugin, installPlugins, setupPlugin, uninstallPlugin } from './plugin.js';
 import { installProviderPackage, uninstallProviderPackage, updateProviderPackage } from './provider.js';
 import { runPresetCommand } from './preset.js';
-import { prepareSetupPreset } from './presetUpgrade.js';
+import { prepareSetupPreset } from './setupPreset.js';
 export { SETUP_VERSION } from './setupVersion.js';
 interface ParsedArgs {
     cloudMode?: 'websocket' | 'qoder';

package/dist/cli.js

@@ -6,7 +6,7 @@ import { isMearlReleaseLine } from './version.js';
 import { ensureOfficialPlugin, installPlugins, setupPlugin, uninstallPlugin } from './plugin.js';
 import { installProviderPackage, uninstallProviderPackage, updateProviderPackage, } from './provider.js';
 import { runPresetCommand } from './preset.js';
-import { prepareSetupPreset } from './presetUpgrade.js';
+import { prepareSetupPreset } from './setupPreset.js';
 import { SETUP_VERSION, SETUP_COMMAND } from './setupVersion.js';
 export { SETUP_VERSION } from './setupVersion.js';
 const baseParsedArgs = () => ({
@@ -177,7 +177,7 @@ function printHelp() {
     const output = `Mearl Setup v${SETUP_VERSION}
 
 Usage:
-  npx --@mearl:registry=https://registry.npmjs.org @mearl/setup [command] [options]
+  npx @mearl/setup [command] [options]
 
 Environment commands:
   install [options]               Install an environment (default command; target: local)
@@ -221,21 +221,23 @@ General options:
   --help, -h                      Show this help
 
 Examples:
-  npx --@mearl:registry=https://registry.npmjs.org @mearl/setup
-  npx --@mearl:registry=https://registry.npmjs.org @mearl/setup --cloud
-  npx --@mearl:registry=https://registry.npmjs.org @mearl/setup --local --cloud
-  npx --@mearl:registry=https://registry.npmjs.org @mearl/setup update
-  npx --@mearl:registry=https://registry.npmjs.org @mearl/setup uninstall --full
-  npx --@mearl:registry=https://registry.npmjs.org @mearl/setup plugin uninstall yuque
-  npx --@mearl:registry=https://registry.npmjs.org @mearl/setup provider install @example/mearl-provider-brow
-  npx --@mearl:registry=https://registry.npmjs.org @mearl/setup extension --full`;
-    console.log(output.replaceAll('npx --@mearl:registry=https://registry.npmjs.org @mearl/setup', SETUP_COMMAND));
+  npx @mearl/setup
+  npx @mearl/setup --cloud
+  npx @mearl/setup --local --cloud
+  npx @mearl/setup update
+  npx @mearl/setup uninstall --full
+  npx @mearl/setup plugin uninstall yuque
+  npx @mearl/setup provider install @example/mearl-provider-brow
+  npx @mearl/setup extension --full`;
+    console.log(output.replaceAll('npx @mearl/setup', SETUP_COMMAND));
 }
 async function runSetupLifecycle(options, dependencies) {
     let preset;
     const callback = options.operation === 'uninstall' ? undefined : { onPresetStatus: (status) => { preset = status; } };
     const lifecycle = dependencies.runLifecycle ?? runMearlLifecycle;
-    const ok = callback ? await lifecycle(options, callback) : await lifecycle(options);
+    const defaultPresetSource = process.env.MEARL_SETUP_DEFAULT_PRESET;
+    const configured = defaultPresetSource ? { ...options, defaultPresetSource } : options;
+    const ok = callback ? await lifecycle(configured, callback) : await lifecycle(configured);
     if (!ok)
         return 1;
     if (!preset) {

package/dist/lifecycle.d.ts

@@ -9,11 +9,14 @@ import { installManagedPlugins, uninstallManagedPlugins } from './managedPlugins
 import { uninstallPlugin } from './plugin.js';
 import { uninstallProviderPackage } from './provider.js';
 import { cleanupUninstalledRuntime } from './runtimeCleanup.js';
-import { prepareSetupPreset } from './presetUpgrade.js';
+import { prepareSetupPreset } from './setupPreset.js';
+import { prepareBrowserSetupPreset } from './browserPreset.js';
 import type { PresetInstallStatus } from './preset.js';
 export type MearlLifecycleOperation = 'install' | 'update' | 'uninstall';
 export interface MearlLifecycleOptions {
     presetSource?: string;
+    /** Distribution default used only when neither local nor browser selection exists. */
+    defaultPresetSource?: string;
     operation: MearlLifecycleOperation;
     cloudMode?: 'websocket' | 'qoder';
     /** Uninstall every registered CLI plugin and Provider in addition to selected environments. */
@@ -27,6 +30,7 @@ export interface MearlLifecycleOptions {
     env?: NodeJS.ProcessEnv;
 }
 export interface MearlLifecycleDependencies {
+    prepareBrowserPreset?: typeof prepareBrowserSetupPreset;
     preparePreset?: typeof prepareSetupPreset;
     onPresetStatus?: (status: PresetInstallStatus) => void;
     /** Prepare the selected manager after packages are usable and before Skill operations. */

package/dist/lifecycle.js

@@ -16,7 +16,8 @@ import { uninstallPlugin } from './plugin.js';
 import { uninstallProviderPackage } from './provider.js';
 import { packageRegistryEnvironment } from './npmRegistry.js';
 import { cleanupUninstalledRuntime } from './runtimeCleanup.js';
-import { prepareSetupPreset } from './presetUpgrade.js';
+import { prepareSetupPreset } from './setupPreset.js';
+import { prepareBrowserSetupPreset } from './browserPreset.js';
 const LEGACY_CLOUD_CLIENT = '@mearl/cloud-client';
 const UNIFIED_CLIENT = '@mearl/client';
 const PROFILE_ORDER = ['local', 'cloud', 'mcp'];
@@ -236,7 +237,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
         writeLine('No installed Mearl environment was detected on the current PATH.');
         if (options.operation === 'uninstall')
             return true;
-        writeLine('Run: npx --@mearl:registry=https://registry.npmjs.org @mearl/setup');
+        writeLine('Run: npx @mearl/setup');
         return false;
     }
     if (options.operation === 'update') {
@@ -281,16 +282,13 @@ export async function runMearlLifecycle(options, dependencies = {}) {
         ? detectPackage(UNIFIED_CLIENT, ['mearl'], packageDetectionOptions)
         : null;
     const detectedClient = detectedClientCandidate?.packageName === UNIFIED_CLIENT ? detectedClientCandidate : null;
+    const preparesPreset = options.operation !== 'uninstall' && !dependencies.prepareSkills && (!options.targetLine || Number(options.targetLine.split('.')[0]) >= 3);
+    const selectsInitialPreset = preparesPreset && !options.skipSkill && !env.MEARL_AUTO_UPDATE_CLIENT_ROOT && !env.MEARL_AUTO_UPDATE_PROFILES;
     let stagedPreset;
-    if (options.operation !== 'uninstall' && (options.presetSource || !options.targetLine || Number(options.targetLine.split('.')[0]) >= 3) && !dependencies.prepareSkills) {
+    if (preparesPreset || (options.operation !== 'uninstall' && options.presetSource && !dependencies.prepareSkills)) {
         try {
             stagedPreset = await (dependencies.preparePreset ?? prepareSetupPreset)({
                 source: options.presetSource, env,
-                installed: [
-                    ...lifecycleSelected.flatMap(profile => detected.get(profile) ? [detected.get(profile)] : []),
-                    ...(detectedClient ? [detectedClient] : []),
-                    ...(autoUpdateClient && env.MEARL_AUTO_UPDATE_CLIENT_ROOT ? [{ packageName: UNIFIED_CLIENT, packageRoot: env.MEARL_AUTO_UPDATE_CLIENT_ROOT }] : []),
-                ],
             });
         }
         catch (error) {
@@ -422,6 +420,24 @@ export async function runMearlLifecycle(options, dependencies = {}) {
             }
         }
     }
+    if (packagesOk && selectsInitialPreset && !stagedPreset && !options.presetSource && lifecycleSelected.some(profile => profile === 'local' || profile === 'mcp')) {
+        try {
+            stagedPreset = await (dependencies.prepareBrowserPreset ?? prepareBrowserSetupPreset)({ env, waitMs: 65_000, writeLine });
+        }
+        catch (error) {
+            writeLine(`Browser preset: ${error instanceof Error ? error.message : String(error)}`);
+            packagesOk = false;
+        }
+    }
+    if (packagesOk && selectsInitialPreset && !stagedPreset && options.defaultPresetSource) {
+        try {
+            stagedPreset = await (dependencies.preparePreset ?? prepareSetupPreset)({ fallbackSource: options.defaultPresetSource, env });
+        }
+        catch (error) {
+            writeLine(`Default preset: ${error instanceof Error ? error.message : String(error)}`);
+            packagesOk = false;
+        }
+    }
     if (packagesOk && options.operation !== 'uninstall' && (stagedPreset || dependencies.prepareSkills)) {
         try {
             if (stagedPreset) {

package/dist/preset.d.ts

@@ -1,7 +1,10 @@
 import { invoke } from '@mearl/client/local';
 import { type JsonObject } from '@mearl/preset';
-import { type BundleLoader } from '@mearl/preset/bundles';
+import { type BundleLoader, type PreparedPreset } from '@mearl/preset/bundles';
 import { PresetInstallationStore } from './presetStore.js';
+export declare const MEARL_INSTALLATION_CONFIG_URL: string;
+/** Runtime overrides apply to this local process, never to browser-supplied install requests. */
+export declare function resolveInstallationConfigUrl(value?: string | undefined, allowLoopback?: boolean): URL;
 export { claimPresetInstallation } from './presetInstallationLease.js';
 export { PresetInstallationStore, presetSelectionRevision } from './presetStore.js';
 export type { PresetInstallReceipt } from './presetStore.js';
@@ -59,6 +62,8 @@ export interface PresetInstallerOptions {
     invoke?: typeof invoke;
 }
 export interface PresetApplyOptions {
+    validatePrepared?: (prepared: PreparedPreset) => Promise<void>;
+    skipUnchanged?: boolean;
     overrides?: JsonObject;
     nodeConfig?: Record<string, JsonObject>;
     signal?: AbortSignal;
@@ -87,7 +92,7 @@ export declare class PresetInstaller {
     /** Save exact resources and desired selection; activate once after runtime setup, then retry via resume. */
     stage(source: string, options?: PresetApplyOptions): Promise<StagedPresetInstallation>;
     apply(source: string, options?: PresetApplyOptions): Promise<PresetInstallStatus>;
-    update(): Promise<PresetInstallStatus>;
+    update(options?: Pick<PresetApplyOptions, 'validatePrepared' | 'skipUnchanged' | 'signal'>): Promise<PresetInstallStatus>;
     resume(expectedRevision: string): Promise<PresetInstallStatus>;
     configure(value: JsonObject): Promise<PresetInstallStatus>;
 }

package/dist/preset.js

@@ -1,11 +1,21 @@
 import { lstat, open } from 'node:fs/promises';
 import { constants } from 'node:fs';
+import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { invoke, invokeLocalHost, listLiveBrowsers, SOCKET_PATH } from '@mearl/client/local';
 import { mergePresetDefaults } from '@mearl/preset';
 import { BundleError, createBundleFetchLoader, preparePreset } from '@mearl/preset/bundles';
 import { PresetInstallationStore, presetSelectionRevision } from './presetStore.js';
+const installationSite = createRequire(import.meta.url)('@mearl/preset/installation-site.json');
+export const MEARL_INSTALLATION_CONFIG_URL = new URL('installation.json', installationSite.url).href;
+/** Runtime overrides apply to this local process, never to browser-supplied install requests. */
+export function resolveInstallationConfigUrl(value = process.env.MEARL_INSTALLATION_CONFIG_URL, allowLoopback = false) {
+    const url = new URL(value || MEARL_INSTALLATION_CONFIG_URL);
+    if (url.username || url.password || url.hash || (url.protocol !== 'https:' && !(allowLoopback && url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname))))
+        throw new Error('Invalid installation configuration URL');
+    return url;
+}
 export { claimPresetInstallation } from './presetInstallationLease.js';
 export { PresetInstallationStore, presetSelectionRevision } from './presetStore.js';
 export { PresetBrowserTransfer } from './presetBrowserTransfer.js';
@@ -225,6 +235,20 @@ export class PresetInstaller {
         const prepared = await preparePreset(sourceUrl(source), { mearlApiVersion: this.store.mearlApiVersion, load: this.options.load ?? createNodePresetLoader(), signal: options.signal });
         if (options.expectedId !== undefined && prepared.preset.id !== options.expectedId)
             throw new BundleError('BUNDLE_INVALID', 'The preset identity differs from the accepted installation');
+        await options.validatePrepared?.(prepared);
+        if (options.skipUnchanged) {
+            const current = await this.store.current();
+            if (presetSelectionRevision(current) !== expectedRevision)
+                throw new BundleError('BUNDLE_CONFLICT', 'The installed preset changed during update');
+            if (current.receipt && current.prepared?.snapshot.revision === prepared.snapshot.revision) {
+                return { revision: current.receipt.revision, activate: async () => {
+                        const status = await this.status();
+                        if (status.revision !== expectedRevision)
+                            throw new BundleError('BUNDLE_CONFLICT', 'The installed preset changed during update');
+                        return status.ready ? status : this.resume(current.receipt.revision);
+                    } };
+            }
+        }
         const receipt = await this.store.apply(prepared, { ...options, expectedRevision });
         let activated = false;
         return { revision: receipt.revision, activate: async () => {
@@ -249,11 +273,11 @@ export class PresetInstaller {
     async apply(source, options = {}) {
         return (await this.stage(source, options)).activate();
     }
-    async update() {
+    async update(options = {}) {
         const current = await this.store.current({ verifyResources: false });
         if (!current.receipt)
             throw new Error('No preset is installed');
-        return this.apply(current.receipt.snapshot.source, { expectedRevision: presetSelectionRevision(current) });
+        return this.apply(current.receipt.snapshot.source, { ...options, expectedRevision: presetSelectionRevision(current) });
     }
     async resume(expectedRevision) {
         const current = await this.store.current();

package/dist/setupPreset.d.ts

@@ -0,0 +1,9 @@
+import { PresetInstaller, type StagedPresetInstallation } from './preset.js';
+/** Preserve the accepted installation and resume its exact resources before Skill operations. */
+export declare function prepareSetupPreset(options: {
+    source?: string;
+    fallbackSource?: string;
+    env?: NodeJS.ProcessEnv;
+}, dependencies?: {
+    installer?: PresetInstaller;
+}): Promise<StagedPresetInstallation | undefined>;

package/dist/setupPreset.js

@@ -0,0 +1,14 @@
+import { PresetInstaller } from './preset.js';
+/** Preserve the accepted installation and resume its exact resources before Skill operations. */
+export async function prepareSetupPreset(options, dependencies = {}) {
+    const installer = dependencies.installer ?? new PresetInstaller({ directory: (options.env ?? process.env).MEARL_CAPABILITY_DIR });
+    if (options.source)
+        return installer.stage(options.source);
+    const current = await installer.store.current();
+    if (current.receipt)
+        return { revision: current.receipt.revision, activate: () => installer.resume(current.receipt.revision) };
+    if (current.activation)
+        return;
+    if (options.fallbackSource)
+        return installer.stage(options.fallbackSource);
+}

package/dist/setupVersion.js

@@ -1,4 +1,4 @@
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 export const SETUP_VERSION = require('../package.json').version;
-export const SETUP_COMMAND = `npx --@mearl:registry=https://registry.npmjs.org @mearl/setup${SETUP_VERSION.includes('-beta.') ? '@' + SETUP_VERSION : ''}`;
+export const SETUP_COMMAND = `npx @mearl/setup${SETUP_VERSION.includes('-beta.') ? '@beta' : ''}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "3.0.0-beta.4",
+  "version": "3.0.0-beta.5",
   "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",
@@ -78,11 +78,11 @@
     "extract-zip": "^2.0.1",
     "ws": "^8.18.3",
     "semver": "^7.8.5",
-    "@mearl/client": "3.0.0-beta.4",
-    "@mearl/provider": "3.0.0-beta.4",
-    "@mearl/daemon-core": "3.0.0-beta.4",
-    "@mearl/preset": "3.0.0-beta.4",
-    "@mearl/browser-core": "3.0.0-beta.4"
+    "@mearl/provider": "3.0.0-beta.5",
+    "@mearl/daemon-core": "3.0.0-beta.5",
+    "@mearl/preset": "3.0.0-beta.5",
+    "@mearl/browser-core": "3.0.0-beta.5",
+    "@mearl/client": "3.0.0-beta.5"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",

package/dist/presetUpgrade.d.ts

@@ -1,13 +0,0 @@
-import { type InstallationConfig } from '@mearl/preset/installation';
-import { PresetInstaller, type StagedPresetInstallation } from './preset.js';
-import { type DetectedGlobalPackage } from './packageManager.js';
-export declare const MEARL_INSTALLATION_CONFIG_URL = "https://f-loat.github.io/mearl/installation.json";
-/** Reuse the installation receipt as the retry marker; organization defaults come from deployment data. */
-export declare function prepareSetupPreset(options: {
-    source?: string;
-    installed?: Array<Pick<DetectedGlobalPackage, 'packageName' | 'packageRoot'>>;
-    env?: NodeJS.ProcessEnv;
-}, dependencies?: {
-    installer?: PresetInstaller;
-    configuration?: () => Promise<InstallationConfig>;
-}): Promise<StagedPresetInstallation | undefined>;

package/dist/presetUpgrade.js

@@ -1,42 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { loadInstallationConfig } from '@mearl/preset/installation';
-import { PresetInstaller } from './preset.js';
-import { detectGlobalPackage } from './packageManager.js';
-import { detectMearlProfiles } from './profiles.js';
-export const MEARL_INSTALLATION_CONFIG_URL = 'https://f-loat.github.io/mearl/installation.json';
-function isLegacyPackage(installation) {
-    try {
-        const manifest = JSON.parse(readFileSync(join(installation.packageRoot, 'package.json'), 'utf8'));
-        return manifest.name === installation.packageName && typeof manifest.version === 'string' && /^[0-2]\.\d+\.\d+(?:[-+][\w.-]+)?$/.test(manifest.version);
-    }
-    catch {
-        return false;
-    }
-}
-/** Reuse the installation receipt as the retry marker; organization defaults come from deployment data. */
-export async function prepareSetupPreset(options, dependencies = {}) {
-    const env = options.env ?? process.env;
-    const installer = dependencies.installer ?? new PresetInstaller({ directory: env.MEARL_CAPABILITY_DIR });
-    if (options.source)
-        return installer.stage(options.source);
-    const current = await installer.store.current();
-    if (current.receipt)
-        return { revision: current.receipt.revision, activate: () => installer.resume(current.receipt.revision) };
-    if (current.activation)
-        return;
-    const client = options.installed === undefined ? detectGlobalPackage('@mearl/client', ['mearl'], { env }) : null;
-    const installed = options.installed ?? [...detectMearlProfiles({ env }).values(), ...(client ? [client] : [])];
-    if (!installed.some(isLegacyPackage))
-        return;
-    const configuration = dependencies.configuration ?? (() => {
-        const url = new URL(env.MEARL_INSTALLATION_CONFIG_URL || MEARL_INSTALLATION_CONFIG_URL);
-        if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)))
-            throw new Error('Installation configuration requires HTTPS or loopback HTTP');
-        return loadInstallationConfig(url, url.origin, AbortSignal.timeout(5_000));
-    });
-    const config = await configuration();
-    if (!config.legacyPreset)
-        throw new Error('Legacy upgrade preset is unavailable. Retry when the installation catalog is available, or select a preset with --preset.');
-    return installer.stage(config.presets[config.legacyPreset].source, { expectedRevision: null, expectedId: config.legacyPreset });
-}