@mearl/setup 3.0.0-beta.0 → 3.0.0-beta.10

package/README.zh-CN.md

@@ -0,0 +1,260 @@
+# @mearl/setup
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+3.0 当前以 beta 发行。使用 `@beta` 入口安装同版本的 setup、运行包和扩展；正式版使用 `latest` 标签。
+
+Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全局安装 setup：
+
+要求 Node.js >= 20.18.0。安装前检查 `node --version`；3.0 beta 继续显式使用 `@beta`，
+避免 npm 在未指定版本时按旧 Node 的兼容性选到历史安装器。
+
+```bash
+npx @mearl/setup@beta [install] [--local] [--cloud] [--cloud-mode <id>] [--mcp]
+npx @mearl/setup@beta update [--local] [--cloud] [--cloud-mode <id>] [--mcp]
+npx @mearl/setup@beta uninstall [--local] [--cloud] [--cloud-mode <id>] [--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>
+npx @mearl/setup@beta preset repair [--replace-skill <name> ...]
+```
+
+浏览器 Provider 独立安装和演进。安装后运行 `mearl <providerId>` 查看该版本声明的能力、
+配置和启动参数。
+
+可选云协议先通过 preset 安装对应能力，再用 `--cloud-mode <id>` 选择。Qoder 配对见 [`@mearl/plugin-qoder`](../plugin-qoder/README.zh-CN.md)；setup 不默认包含或安装它。
+
+## 安装与注册 Skill 插件
+
+一个命令安装 skill 并注册它的 CLI、SDK 和 MCP 能力：
+
+```bash
+npx @mearl/setup@beta plugin install https://github.com/mearlhq/mearl --skill browser-tab-manager --yes
+mearl tabs summary
+```
+
+安装参数传给固定版本的公共 Skills CLI（当前 skills@1.5.0，兼容项目的 Node 最低版本），使用全局共享目录。公共 CLI 的默认 symlink 和复制模式都可注册；复制模式通过 list --global --json 确认本次成功结果对应的 canonical path，不猜测目录，也不扫描其他 Skills。自定义 CLI 可通过 MEARL_SKILLS_PATH 指定。参数不接受截断后置选项的 -- 分隔符。
+
+安装宿主提供的本地插件目录决定哪些能力由 preset 管理。install/update 维护目录中的托管注册，保留用户自行注册的插件。卸载最后一个依赖环境时移除托管插件与 Mearl Skill；其他环境需要时保留。配置准备、宿主同步和实际安装状态共用 [安装合同](../../docs/preset-installation.zh-CN.md)。
+
+Native preset 批次新建的插件注册使用 setup 托管归属，后续通过 Agent 更新仍保留该归属；同目录已有的用户注册保持原归属，自定义用户别名也会保留。托管卸载遇到用户别名共用同一 Skill 时，只清除托管注册并保留 Skill 文件。
+
+GUI 和 CLI 使用同一套 preset 安装器及覆盖规则。已保存的安装尚未完成时，运行 `preset repair` 从接受的本地资源重试，不重新下载 preset，也不隐式覆盖冲突来源。显式重复指定 `--replace-skill` 即授权本次替换这些 Skill 的来源或同名旧插件注册：
+
+```bash
+npx @mearl/setup@beta preset repair --replace-skill example-skill --replace-skill another-skill
+```
+
+已安装的 Skill 仅修复注册；来源冲突项重新安装。未列出的冲突仍会阻止安装，声明外的工具名与变更后的安装身份也会被拒绝。覆盖授权不会保留到后续普通修复或自动更新。缺少浏览器权限时仍需在扩展中授权。输出沿用 preset JSON，已就绪退出 `0`、仍有待完成项退出 `3`、安装失败退出 `1`，无效参数退出 `2`。
+
+自动注册默认使用安装目录名；入口可声明 `name` 指定简短命令名。
+重装会刷新同名绑定。JavaScript 入口必须默认导出 `register(app)`，Python 入口必须导出 `register(app)` 函数；完整协议见
+[插件运行时合同](../../docs/plugin-runtime.zh-CN.md)。
+
+已通过其他渠道分发的 skill 或自定义入口，可以直接传入路径注册：
+
+```bash
+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`。
+命令检查入口注册函数，然后保存绝对入口路径，同名注册更新绑定。
+两种注册流程都会检查本机 `@mearl/client` 和 `@mearl/native-host`：缺失或低于当前 setup 版本时，
+复用已有包管理器安装 setup 的对应版本，更新后再次验证；更高版本保持不动。
+native-host 会幂等初始化 Skills 模式。基础环境补齐或初始化失败时保留已安装的 skill，并停止注册。
+JavaScript 插件可导出 `setup({ runCommand })`，在注册前准备 Skill 自己的依赖。两种安装入口都会等待执行完成，失败时停止注册。首次使用的依赖检查由 Skill 自行处理，见 [client 契约](../client/README.zh-CN.md#skill-插件)。
+
+注册后可在任意目录运行 `mearl <name> --help`，也可通过 `@mearl/client` 的 `invokePlugin` 或 MCP 的 `plugin_invoke` 工具调用。日常调用不更新 Skill 源码；已选目录中的缺失插件会触发一次按需安装。Skill 自身的依赖由安装钩子和首次使用检查准备。
+
+不再需要插件时执行：
+
+```bash
+npx @mearl/setup@beta plugin uninstall tabs
+```
+
+若入口位于 `~/.agents/skills/<skill>/`，setup 会先执行
+`skills remove <skill> --global --yes`，成功后清除该 Skill 对应的全部插件注册；
+入口目录已被手动删除时会让 Skills 仍能识别本次移除，从而一并清理其跟踪记录。
+移除失败时保留注册以便重试。手工注册的其他路径只解除 Mearl 注册，不删除源码。
+重复卸载未注册名称会成功返回，不产生改动。
+
+## 管理浏览器 Provider
+
+Provider 由 npm 包分发，但包本身无需暴露 CLI 或安装脚本。setup 使用当前 npm 包管理器
+完成全局包生命周期，再读取包内的 `package.json#mearl.provider` 元数据登记协议入口、
+可创建的浏览器类型名称及其表单参数：
+
+```bash
+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 沿用调用方的包管理器配置。安装沿用启动 setup 的包管理器，
+更新和卸载沿用当前 Provider 的原包管理器。Provider 登记只保存
+经过校验的包名、安装目录和包内入口；不接受包自行注入启动命令、参数、工作目录或环境变量。
+卸载仅在包管理器成功移除包后清除登记，以便失败时可以重试。
+
+## 行为
+
+- Mearl 自有 npm 包的安装和更新固定使用 `https://registry.npmjs.org/`，与最新版本查询使用同一来源；第三方包沿用当前包管理器的源配置。
+- `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` 中的
+  `mearl-native-host`、`mearl-cloud-server`、`mearl-mcp-server` 自动检测，可同时处理
+  多个已安装环境。
+- `--local`、`--cloud` 与 `--mcp` 可以组合，显式传入时只处理选中的环境；
+  `--cloud-mode <id>` 同时选择 cloud 环境，模式实现必须来自已安装能力。
+- 已有环境沿用其原包管理器和全局安装前缀；首次安装沿用启动 setup 的包管理器。
+- `uninstall` 也识别 `npm link` 或 `dev:link` 注册到 npm 全局目录的开发软链，
+  通过原 npm 前缀移除包与命令链接，保留仓库源码。安装和更新的自动检测仅处理常规全局安装。
+- cloud 环境统一管理 `@mearl/cloud-server` 与 `@mearl/client`：WebSocket 模式首次安装后
+  启动 Server，更新后仅在 Server 原本运行时重启；其他 mode 由安装的 `cloud.server.<id>` 处理；卸载前均调用 `stop`。
+- local/cloud 共用一份 `@mearl/client`；组合安装只处理一次，卸载单个环境时若另一个环境仍在使用则保留。
+- 从 2.5.x 更新 cloud 环境时会先卸载旧 `@mearl/cloud-client`，避免它遗留的 `mearl` bin 与统一 client 冲突。
+- local/cloud 共用的全局 mearl skill 通过 `skills` 的 JSON 清单定位，只处理一次。
+- 安装和更新通过 `skills add` 从公开仓库重新安装全局 mearl skill，并关联当前检测到的 Agent；更新须确认本次安装完成并核对全局 JSON 清单，不能仅依据第三方更新命令的退出码。
+  可用 `--skip-skill` 跳过。
+- 卸载一个环境但另一个仍依赖全局 mearl skill 时会保留 skill。
+- 已选择 preset 的自动维护保留用户注册；托管卸载遇到同目录的用户别名时只移除托管注册并保留共享 Skill。
+- `uninstall --full` 在环境卸载之外，还会逐项卸载所有已注册 CLI 插件与浏览器 Provider。
+  Skills 安装的插件会同时移除 Skill；手工注册的外部插件只清除注册、保留源码；Provider
+  只有在包管理器成功卸载 npm 包后才清除注册。单项失败不阻止其他项继续清理，命令最终返回非零。
+  该选项不删除 Chrome 扩展；`extension --full` 仍表示安装扩展及完整本地环境。
+- `uninstall --full` 在所有环境、插件与 Provider 成功移除后统一收尾：停止插件执行服务，
+  确认没有活跃或退出状态未明的任务，再删除任务历史、源码快照、服务日志和已结束宿主的页面会话文件。只卸载部分环境、单项失败或服务重新启动时保留共享缓存。
+  即使包和注册已移除，也可以再次运行该命令完成缓存收尾。自定义 `MEARL_PLUGIN_DIR` 只清理该注册表的执行缓存。
+  记事本、迭代记录、配置与身份、插件持久状态、Provider 私有数据、浏览器配置及用户导出的设计稿均保留；
+  CDP 标签 ID 计数也保留，防止旧请求命中新标签。
+- `--mcp` 的客户端配置和清理由 `@mearl/mcp-server` 自己的命令完成。
+- 默认的 `install` / `update` 不处理浏览器扩展。`extension` 是独立命令：从
+  `https://github.com/mearlhq/mearl/releases/download/v<version>/` 读取同版本 beta 扩展发行元数据（正式 setup 使用 `releases/latest/download/`）并下载对应的 `mearl-chrome-v*.zip`，原子解压到
+  `~/.mearl/chrome-extension`。首次安装通过浏览器级 CDP 的 `Extensions.loadUnpacked`
+  加载；后续更新由 `mearl check --local --json` 确认当前扩展仍来自 setup 管理目录后，直接替换
+  文件并通过 Native Host 触发扩展 reload。固定目录和 manifest 中的 `key` 保证扩展 ID
+  与浏览器存储保持稳定。
+- `extension --full` 会先安装或更新扩展，再复用 local profile 安装
+  `@mearl/client`、安装并初始化 `@mearl/native-host`，最后安装全局 Mearl Skill。
+  两部分都会尽量执行；任一步失败时命令返回非零退出码，已安装的部分会保留。它不安装
+  cloud 或 MCP 环境。
+- 下载前会通过 CDP 检查同 ID 插件的来源。未安装，或来源为固定目录中的 `UNPACKED`
+  插件时可继续；Chrome 商店、企业策略或其他本地目录安装的版本默认保持不变。只有显式
+  传入 `--force` 才会接管并替换这些版本。
+
+## 安装或更新浏览器扩展
+
+```bash
+npx @mearl/setup@beta extension
+```
+
+首次使用时可一次安装完整的本地浏览器环境：
+
+```bash
+npx @mearl/setup@beta extension --full
+```
+
+首次安装、旧版 setup 扩展首次迁移，或 Native Host reload 不可用时才需要 CDP。如果
+Chrome 尚未开放 CDP，交互命令会提示打开
+`chrome://inspect/#remote-debugging`、启用远程调试并允许连接，然后等待安装完成。面向人的
+安装指引不要添加 `--yes`。无 TTY 环境使用 `npx @mearl/setup@beta extension --yes`；它只尝试
+一次，CDP 不可用时立即中断。无法确认 setup 管理来源且 CDP 不可用时不会下载或修改插件
+目录，打开 CDP 后重新执行同一命令即可。Chrome 版本过低、缺少扩展安装所需的 CDP 方法时，
+命令会中断并提示升级 Chrome。
+
+该命令每次都读取下载页上的最新插件版本，不要求与 setup、CLI 或 Native Host 同版本。
+CDP 来源检查和 `Extensions.loadUnpacked` 复用同一条连接，避免一次安装重复请求授权。
+安装成功后目录内会保存 setup 管理标记；`mearl check --local --json` 同时从当前运行扩展读取该
+标记，只有两侧路径一致时才允许无 CDP 更新。如果用户后来改装 Chrome 商店版本，运行中
+的扩展不会返回 setup 标记，命令会重新通过 CDP 检查来源，并在未传 `--force` 时保持商店
+版本不变。
+
+setup 管理的扩展会读取远端 `config.json` 检查新版本，但不会静默更新。发现更高版本后，
+DevTools 面板的设置按钮会显示红点，快捷设置中提供“立即更新”和对应版本的“更新日志”。
+只有用户点击“立即更新”后，Native Host 才会重新校验远端版本、setup 管理标记、下载地址、
+可选的 SHA256 和压缩包 manifest，再原子替换目录并 reload。该入口不会回退到 CDP；商店版、
+企业策略版和其他本地目录版本不会进入 setup 更新链路。对于 Chrome 自身管理并已下载完成的
+更新，扩展只被动监听 `runtime.onUpdateAvailable`，沿用相同的更新提示并由用户点击 reload；不会
+调用 `runtime.requestUpdateCheck()` 主动检查。
+
+## 跟随浏览器扩展自动更新
+
+浏览器扩展与 Native Host 首次建联时会交换版本。每次扩展后台启动只检查一次；当扩展
+进入更高的 `major.minor` release line 时，旧 Host 会在保持当前连接可用的前提下，调用
+对应 `major.minor.x` 范围内最新的 `@mearl/setup`，把 `@mearl/native-host` 与
+`@mearl/client` 一起更新到该范围内的最新版本。成功后 Host 退出，扩展通过已有重连机制
+启动新版本。只有两个本地 CLI 版本一致且都属于扩展的 release line 时，更新才会被视为成功。
+
+自动更新不会降级较新的 Host，也不会改动 cloud、MCP 或独立安装的 Mearl Skill。
+目标 npm 版本尚未发布、网络不可用或更新失败时，旧 Host 会继续运行；下一次扩展后台
+生命周期可重新尝试，也可手动执行 `npx @mearl/setup@beta update --local`。
+
+## 人工与 Agent 使用
+
+- 人工在终端执行时不加 `--yes`，需要选择 Skill 安装目标或 MCP 客户端时会显示交互提示。
+- Agent、CI 或其他无 TTY 环境应加 `--yes`（也可写
+  `--non-interactive`）。首次安装会选择已检测到的 Agent / MCP 客户端，卸载会清理
+  所有已检测到的相关配置。
+- 无 TTY 环境执行 `install` 或 `uninstall` 却未加上述参数时，会在任何改动前退出并提示正确命令。
+- 退出码 `0` 表示完整成功，`1` 表示执行未完成，`2` 表示参数或交互模式不适用。
+
+## 示例
+
+```bash
+# 默认安装本地浏览器环境
+npx @mearl/setup
+
+# 与上一条等价
+npx @mearl/setup@beta install
+
+# Agent / CI 无交互安装
+npx @mearl/setup@beta --yes
+
+# 安装云端 Agent 环境
+npx @mearl/setup@beta --cloud
+
+# 同一台机器同时作为本地浏览器宿主和云端 Agent
+npx @mearl/setup@beta --local --cloud
+
+# 自动更新当前 PATH 中检测到的全部 Mearl 环境
+npx @mearl/setup@beta update
+
+# 独立安装或更新到最新浏览器扩展
+npx @mearl/setup@beta extension
+
+# 安装完整本地环境（client、Native Host、Skill 和扩展）
+npx @mearl/setup@beta extension --full
+
+# 只卸载本地环境
+npx @mearl/setup@beta uninstall --local
+
+# 自动检测并无交互卸载
+npx @mearl/setup@beta uninstall --yes
+
+# 卸载环境，并清理全部 CLI 插件与 Provider
+npx @mearl/setup@beta uninstall --full
+
+# 安装可选浏览器 Provider
+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 是统一的便利入口。
+
+## Preset 安装
+
+`mearl-setup preset apply <source-url-or-path>` 准备确切资源、激活本机 Node 选择，并向兼容扩展同步同一批浏览器资源；`preset update` 保留用户覆盖，`preset status` 只读检查实际就绪状态。退出码 3 表示存在待同步/安装组件。完整扩展、默认设置、Skills/Provider 和网页一键安装使用同一实际状态核验，见 [本机安装合同](../../docs/preset-installation.zh-CN.md)。
+
+install/update 在替换包前保存选中 Preset 的确切资源和期望选择，运行时初始化后同步宿主并安装 Skills；`extension --full` 在替换扩展前完成同一准备流程。已有本机选择优先保留，显式 `--preset` 用于更新或修复资源。配置或资源不可用时停止包变更；部分升级后的重试使用已保存记录。卸载不准备或安装 Preset。
+
+默认目录为公共站点的 `installation.json`，可通过 `MEARL_INSTALLATION_CONFIG_URL` 指定其他 HTTPS 目录（本地验证允许回环 HTTP）。目录采用网页安装的校验合同；本机与浏览器未全部确认时报告 pending。
+
+## 浏览器 preset 与发行入口
+
+主动执行 setup 时，先沿用本机已选 preset；本机未选择时，在运行时初始化后、安装 Skill 前采用已连接浏览器的受信 preset。显式 `--preset <source>` 优先。多个浏览器的选择不同、来源不受信或状态读取失败时要求显式选择。首次连接最多等待约一分钟；浏览器关闭时只安装基础环境并说明重试方式。普通连接和后台核心更新不会自动安装首次本机 preset。
+
+发行包可设置本机进程环境变量 `MEARL_SETUP_DEFAULT_PRESET` 提供默认清单来源；默认值仅在两端均无选择时生效，插件、Provider、卸载等子命令保持原行为。安装与状态核验仍由公共安装器负责。

package/dist/browserExtension.js

@@ -6,15 +6,15 @@ import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { runUnifiedCheck } from '@mearl/client/check';
 import { CLIENT_VERSION, invoke as invokeLocalMearl } from '@mearl/client/local';
-import extractZip from 'extract-zip';
+import AdmZip from 'adm-zip';
 import WebSocket from 'ws';
 import { compareMearlReleaseVersions, isMearlReleaseVersion } from './version.js';
 export const MEARL_EXTENSION_DOWNLOAD_PAGE = SETUP_VERSION.includes('-beta.')
-    ? `https://github.com/F-loat/mearl/releases/tag/v${SETUP_VERSION}`
-    : 'https://github.com/F-loat/mearl/releases/latest';
+    ? `https://github.com/mearlhq/mearl/releases/tag/v${SETUP_VERSION}`
+    : 'https://github.com/mearlhq/mearl/releases/latest';
 export const MEARL_EXTENSION_REMOTE_CONFIG_URL = SETUP_VERSION.includes('-beta.')
-    ? `https://github.com/F-loat/mearl/releases/download/v${SETUP_VERSION}/config.json`
-    : 'https://github.com/F-loat/mearl/releases/latest/download/config.json';
+    ? `https://github.com/mearlhq/mearl/releases/download/v${SETUP_VERSION}/config.json`
+    : 'https://github.com/mearlhq/mearl/releases/latest/download/config.json';
 export const MEARL_EXTENSION_DIRECTORY_NAME = 'chrome-extension';
 export const MEARL_EXTENSION_ID = 'aoehhjnofngknnjefamjbplchbolghkm';
 export const MEARL_EXTENSION_SETUP_MARKER = '.mearl-setup.json';
@@ -52,7 +52,7 @@ export function extensionArchiveUrl(version) {
     if (!isMearlReleaseVersion(version)) {
         throw new Error(`Invalid Mearl browser extension version: ${version}`);
     }
-    return `https://github.com/F-loat/mearl/releases/download/v${version}/mearl-chrome-v${version}.zip`;
+    return `https://github.com/mearlhq/mearl/releases/download/v${version}/mearl-chrome-v${version}.zip`;
 }
 function validateExtensionRelease(release) {
     if (!isMearlReleaseVersion(release.version)) {
@@ -414,6 +414,22 @@ function readExtensionManifest(directory) {
     }
     return parsed;
 }
+async function extractExtensionArchive(archivePath, destination) {
+    const archive = new AdmZip(archivePath);
+    // Extension releases contain ordinary files and directories, never symlinks.
+    // Validate every entry before writing anything into the fresh staging directory.
+    for (const entry of archive.getEntries()) {
+        const name = entry.entryName;
+        const type = (entry.header.attr >>> 16) & 0o170000;
+        if (name.includes('\\') || name.includes('\0') ||
+            path.posix.isAbsolute(name) || path.win32.isAbsolute(name) ||
+            name.split('/').some(part => part === '..' || part === '.') ||
+            (type !== 0 && type !== 0o100000 && type !== 0o040000)) {
+            throw new Error('Extension archive contains an unsafe entry');
+        }
+    }
+    await archive.extractAllToAsync(destination, false);
+}
 async function downloadAndReplaceExtension(releaseInput, targetDirectory, fetchImpl, extractArchive) {
     const release = validateExtensionRelease(releaseInput);
     const parentDirectory = path.dirname(targetDirectory);
@@ -462,7 +478,7 @@ export async function updateSetupManagedBrowserExtensionFiles(options, dependenc
     }
     const fetchImpl = dependencies.fetch ?? fetch;
     const extractArchive = dependencies.extractArchive ??
-        ((archivePath, destination) => extractZip(archivePath, { dir: destination }));
+        extractExtensionArchive;
     const release = await downloadAndReplaceExtension(options.release, targetDirectory, fetchImpl, extractArchive);
     return { ...release, path: targetDirectory };
 }
@@ -470,7 +486,7 @@ export async function installMearlBrowserExtension(options = {}, dependencies =
     const connectCdp = dependencies.connectCdp ?? connectBrowserExtensionViaCdp;
     const fetchImpl = dependencies.fetch ?? fetch;
     const extractArchive = dependencies.extractArchive ??
-        ((archivePath, destination) => extractZip(archivePath, { dir: destination }));
+        extractExtensionArchive;
     const loadUnpacked = dependencies.loadUnpacked ?? loadUnpackedViaCdp;
     const inspectInstallation = dependencies.inspectInstallation ?? inspectMearlExtensionViaCdp;
     const inspectInstalled = dependencies.inspectInstalled ?? inspectSetupManagedExtension;

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 === undefined || 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,16 +5,17 @@ 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';
+    cloudMode?: string;
     force?: boolean;
     full?: boolean;
     help: boolean;
     operation?: MearlLifecycleOperation | 'extension' | 'plugin' | 'provider' | 'preset';
-    presetCommand?: 'apply' | 'update' | 'status';
+    presetCommand?: 'apply' | 'update' | 'status' | 'repair';
     presetSource?: string;
+    presetReplaceSkills?: string[];
     pluginName?: string;
     pluginPath?: string;
     pluginInstallArgs?: string[];

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 = () => ({
@@ -26,11 +26,33 @@ function commanderError(error) {
 }
 export function parseSetupArgs(argv) {
     if (argv[0] === 'preset') {
+        if (argv[1] === 'repair') {
+            const command = new Command('preset repair')
+                .exitOverride()
+                .configureOutput({ writeErr: () => { }, writeOut: () => { } })
+                .allowExcessArguments(false)
+                .option('--replace-skill <name>', 'Replace the named Skill source or conflicting plugin registration', (name, previous) => [...previous, name], []);
+            try {
+                command.parse(argv.slice(2), { from: 'user' });
+            }
+            catch (error) {
+                if (error instanceof CommanderError) {
+                    if (error.code === 'commander.helpDisplayed')
+                        return { ...baseParsedArgs(), help: true };
+                    throw commanderError(error);
+                }
+                throw error;
+            }
+            const names = command.opts().replaceSkill;
+            if (names.length > 256 || new Set(names).size !== names.length || names.some(name => !/^[a-z][a-z0-9-]{0,79}$/.test(name)))
+                throw new Error('--replace-skill requires unique valid Skill names (up to 256)');
+            return { ...baseParsedArgs(), operation: 'preset', presetCommand: 'repair', ...(names.length ? { presetReplaceSkills: names } : {}) };
+        }
         if (argv[1] === 'apply' && argv.length === 3 && argv[2])
             return { ...baseParsedArgs(), operation: 'preset', presetCommand: 'apply', presetSource: argv[2] };
         if ((argv[1] === 'update' || argv[1] === 'status') && argv.length === 2)
             return { ...baseParsedArgs(), operation: 'preset', presetCommand: argv[1] };
-        throw new Error('preset requires apply <source-url-or-path>, update, or status');
+        throw new Error('preset requires apply <source-url-or-path>, update, repair [--replace-skill <name>], or status');
     }
     if (argv[0] === 'provider') {
         const command = argv[1];
@@ -87,7 +109,7 @@ export function parseSetupArgs(argv) {
             .configureOutput({ writeErr: () => { }, writeOut: () => { } })
             .option('--local')
             .option('--cloud')
-            .option('--qoder-cloud')
+            .option('--cloud-mode <id>')
             .option('--mcp')
             .option('--target-line <major.minor.x>')
             .option('--skip-skill')
@@ -98,9 +120,8 @@ export function parseSetupArgs(argv) {
             command.option('--full');
         command.action(() => {
             const options = command.opts();
-            if (options.cloud && options.qoderCloud) {
-                throw new Error('--cloud and --qoder-cloud cannot be used together');
-            }
+            if (options.cloudMode !== undefined && !/^[a-z][a-z0-9-]{0,63}$/.test(options.cloudMode))
+                throw new Error('--cloud-mode requires a valid installed mode ID');
             if (options.targetLine && !isMearlReleaseLine(options.targetLine)) {
                 throw new Error('--target-line requires a valid Mearl release line such as 2.3.x');
             }
@@ -114,15 +135,15 @@ export function parseSetupArgs(argv) {
             const profiles = [];
             if (options.local)
                 profiles.push('local');
-            if (options.cloud || options.qoderCloud)
+            if (options.cloud || options.cloudMode)
                 profiles.push('cloud');
             if (options.mcp)
                 profiles.push('mcp');
             parsed = {
                 ...baseParsedArgs(),
                 operation,
-                ...(options.cloud || options.qoderCloud
-                    ? { cloudMode: options.qoderCloud ? 'qoder' : 'websocket' }
+                ...(options.cloud || options.cloudMode
+                    ? { cloudMode: options.cloudMode ?? 'websocket' }
                     : {}),
                 ...(profiles.length > 0 ? { profiles } : {}),
                 ...(options.full ? { full: true } : {}),
@@ -187,6 +208,7 @@ Environment commands:
 Integration commands:
   preset apply <source>          Apply a preset, synchronize hosts and install declared components
   preset update                  Update the selected preset, preserving user overrides
+  preset repair                  Retry the installed preset using its accepted resources
   preset status                  Report actual readiness (exit 3 when synchronization is pending)
   plugin install <arguments...>   Install Skills and register their CLI plugins
   plugin uninstall <name>        Uninstall one CLI plugin
@@ -201,7 +223,7 @@ Browser extension:
 Environment options:
   --local                         Manage @mearl/native-host and @mearl/client
   --cloud                         Manage cloud packages in WebSocket server mode
-  --qoder-cloud                   Manage cloud packages in Qoder pairing mode
+  --cloud-mode <id>                Manage cloud packages using an installed mode
   --mcp                           Manage @mearl/mcp-server and its configuration
   --target-line <major.minor.x>   Use the latest packages in one release line
   --preset <source>               Apply a preset after installing or updating the environment
@@ -214,6 +236,9 @@ Extension options:
   --full                          Install the extension and complete local environment
   --force                         Replace an extension managed by another source
 
+Preset repair options:
+  --replace-skill <name>           Replace one Skill source or conflicting registration; repeat for more
+
 General options:
   --yes, -y                       Accept prompts and detected defaults
   --non-interactive               Alias for --yes, intended for Agents and CI
@@ -228,6 +253,7 @@ Examples:
   npx @mearl/setup uninstall --full
   npx @mearl/setup plugin uninstall yuque
   npx @mearl/setup provider install @example/mearl-provider-brow
+  npx @mearl/setup preset repair --replace-skill example-skill
   npx @mearl/setup extension --full`;
     console.log(output.replaceAll('npx @mearl/setup', SETUP_COMMAND));
 }
@@ -235,7 +261,9 @@ 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) {
@@ -269,7 +297,10 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
     }
     if (parsed.operation === 'preset') {
         try {
-            const result = await (dependencies.runPreset ?? runPresetCommand)(parsed.presetCommand, parsed.presetSource);
+            const run = dependencies.runPreset ?? runPresetCommand;
+            const result = parsed.presetReplaceSkills
+                ? await run(parsed.presetCommand, parsed.presetSource, { replaceSkills: parsed.presetReplaceSkills })
+                : await run(parsed.presetCommand, parsed.presetSource);
             console.log(JSON.stringify(result, null, 2));
             return result.ready ? 0 : 3;
         }

package/dist/lifecycle.d.ts

@@ -5,17 +5,22 @@ import { detectGlobalPackage, type PackageManagerInstallation, type PackageDetec
 import { type DetectedMearlProfiles, type MearlProfile } from './profiles.js';
 import { uninstallNativeHostArtifacts } from './nativeHost.js';
 import { type CommandRunner } from '@mearl/daemon-core';
+import { readInstallationManagement } from '@mearl/daemon-core/installation';
+import { claimPresetInstallation } from './presetInstallationLease.js';
 import { installManagedPlugins, uninstallManagedPlugins } from './managedPlugins.js';
 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';
+    cloudMode?: string;
     /** Uninstall every registered CLI plugin and Provider in addition to selected environments. */
     full?: boolean;
     /** @deprecated Use profiles when selecting one or more composable environments. */
@@ -27,6 +32,9 @@ export interface MearlLifecycleOptions {
     env?: NodeJS.ProcessEnv;
 }
 export interface MearlLifecycleDependencies {
+    readManagement?: typeof readInstallationManagement;
+    claimLifecycle?: () => ReturnType<typeof claimPresetInstallation>;
+    prepareBrowserPreset?: typeof prepareBrowserSetupPreset;
     preparePreset?: typeof prepareSetupPreset;
     onPresetStatus?: (status: PresetInstallStatus) => void;
     /** Prepare the selected manager after packages are usable and before Skill operations. */