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

package/README.md

@@ -4,31 +4,32 @@
 
 Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全局安装 setup：
 
+要求 Node.js >= 20.18.0。安装前检查 `node --version`；3.0 beta 继续显式使用 `@beta`，
+避免 npm 在未指定版本时按旧 Node 的兼容性选到历史安装器。
+
 ```bash
-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 [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>` 查看该版本声明的能力、
 配置和启动参数。
 
-在 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。
+可选云协议先通过 preset 安装对应能力，再用 `--cloud-mode <id>` 选择。Qoder 配对见 [`@mearl/plugin-qoder`](../plugin-qoder/README.md)；setup 不默认包含或安装它。
 
 ## 安装与注册 Skill 插件
 
 一个命令安装 skill 并注册它的 CLI、SDK 和 MCP 能力：
 
 ```bash
-npx @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/mearlhq/mearl/tree/codex/open-source-ready --skill browser-tab-manager --yes
 mearl tabs summary
 ```
 
@@ -38,6 +39,14 @@ mearl tabs summary
 
 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.md)。
@@ -96,13 +105,12 @@ npx @mearl/setup@beta provider uninstall example-device
   `mearl-native-host`、`mearl-cloud-server`、`mearl-mcp-server` 自动检测，可同时处理
   多个已安装环境。
 - `--local`、`--cloud` 与 `--mcp` 可以组合，显式传入时只处理选中的环境；
-  `--qoder-cloud` 选择相同的 cloud 环境并记录 Qoder 配对模式，不能与 `--cloud` 同时使用。
+  `--cloud-mode <id>` 同时选择 cloud 环境，模式实现必须来自已安装能力。
 - 已有环境沿用其原包管理器和全局安装前缀；首次安装沿用启动 setup 的包管理器。
 - `uninstall` 也识别 `npm link` 或 `dev:link` 注册到 npm 全局目录的开发软链，
   通过原 npm 前缀移除包与命令链接，保留仓库源码。安装和更新的自动检测仅处理常规全局安装。
 - cloud 环境统一管理 `@mearl/cloud-server` 与 `@mearl/client`：WebSocket 模式首次安装后
-  启动 Server，更新后仅在 Server 原本运行时重启；Qoder 模式由相同的 `start` 命令生成
-  新配对但不起服务；卸载前均调用 `stop`。
+  启动 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 清单定位，只处理一次。
@@ -121,7 +129,7 @@ npx @mearl/setup@beta provider uninstall example-device
   CDP 标签 ID 计数也保留，防止旧请求命中新标签。
 - `--mcp` 的客户端配置和清理由 `@mearl/mcp-server` 自己的命令完成。
 - 默认的 `install` / `update` 不处理浏览器扩展。`extension` 是独立命令：从
-  `https://github.com/F-loat/mearl/releases/download/v3.0.0-beta.1/` 读取同版本 beta 扩展发行元数据（正式 setup 使用 `releases/latest/download/`）并下载对应的 `mearl-chrome-v*.zip`，原子解压到
+  `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

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.js

@@ -18,7 +18,7 @@ export async function prepareBrowserSetupPreset(options = {}, dependencies = {})
         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));
+        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) => {

package/dist/cli.d.ts

@@ -8,13 +8,14 @@ import { runPresetCommand } from './preset.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

@@ -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));
 }
@@ -271,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

@@ -18,7 +18,7 @@ export interface MearlLifecycleOptions {
     /** 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. */

package/dist/lifecycle.js

@@ -136,12 +136,12 @@ async function runHook(profile, operation, detected, runner, existsSync, env, wr
                 return false;
             }
             const running = /\[CloudServer\]\s+Status:\s+running\b/.test(status.stdout);
-            const qoderMode = cloudMode === 'qoder' || /\[CloudServer\]\s+Mode:\s+qoder\b/.test(status.stdout);
-            if (operation === 'update' && !running && !qoderMode) {
+            const pluginMode = Boolean(cloudMode && cloudMode !== 'websocket') || /\[CloudServer\]\s+Mode:\s+(?!websocket\b)\S+/.test(status.stdout);
+            if (operation === 'update' && !running && !pluginMode) {
                 writeLine('Hook: cloud update skipped because cloud-server is not running.');
                 return true;
             }
-            args = [running && !qoderMode ? 'restart' : 'start'];
+            args = [running && !pluginMode ? 'restart' : 'start'];
         }
     }
     else {

package/dist/preset.d.ts

@@ -65,7 +65,6 @@ export interface PresetApplyOptions {
     validatePrepared?: (prepared: PreparedPreset) => Promise<void>;
     skipUnchanged?: boolean;
     overrides?: JsonObject;
-    nodeConfig?: Record<string, JsonObject>;
     signal?: AbortSignal;
     expectedRevision?: string | null;
     expectedId?: string;
@@ -93,7 +92,14 @@ export declare class PresetInstaller {
     stage(source: string, options?: PresetApplyOptions): Promise<StagedPresetInstallation>;
     apply(source: string, options?: PresetApplyOptions): Promise<PresetInstallStatus>;
     update(options?: Pick<PresetApplyOptions, 'validatePrepared' | 'skipUnchanged' | 'signal'>): Promise<PresetInstallStatus>;
-    resume(expectedRevision: string): Promise<PresetInstallStatus>;
+    resume(expectedRevision: string, options?: {
+        replaceSkills?: readonly string[];
+    }): Promise<PresetInstallStatus>;
+    repair(options?: {
+        replaceSkills?: readonly string[];
+    }): Promise<PresetInstallStatus>;
     configure(value: JsonObject): Promise<PresetInstallStatus>;
 }
-export declare function runPresetCommand(command: 'apply' | 'update' | 'status', source?: string): Promise<PresetInstallStatus>;
+export declare function runPresetCommand(command: 'apply' | 'update' | 'status' | 'repair', source?: string, options?: {
+    replaceSkills?: readonly string[];
+}): Promise<PresetInstallStatus>;

package/dist/preset.js

@@ -112,12 +112,12 @@ export class PresetInstaller {
             }
         }));
     }
-    async componentStatus(install, receipt) {
+    async componentStatus(install, receipt, replaceSkills) {
         const target = (this.options.hosts?.() ?? localHosts(install))[0];
         if (!target)
             return {};
         try {
-            const result = await this.invokeHost(install ? 'preset_components_install' : 'preset_components_status', { installationRevision: receipt.revision }, target, install ? 900 : 15, install);
+            const result = await this.invokeHost(install ? 'preset_components_install' : 'preset_components_status', { installationRevision: receipt.revision, ...(install && replaceSkills?.length ? { replaceSkills } : {}) }, target, install ? 900 : 15, install);
             if (result?.installationRevision !== receipt.revision || result?.nodeRevision !== receipt.nodeRevision || !Array.isArray(result?.components))
                 throw new Error('Component installation host requires an update');
             if (result.catalogReady !== undefined && typeof result.catalogReady !== 'boolean')
@@ -151,7 +151,7 @@ export class PresetInstaller {
         result.nodeRevision = receipt.nodeRevision;
         result.browserRevision = receipt.browserRevision;
         result.browserSyncRequired = receipt.browserSyncRequired === true;
-        result.localComponentCount = Object.values(preset.packages).filter(entry => entry.enabled !== false && entry.runtimes?.includes('node')).length
+        result.localComponentCount = Object.values(preset.packages).filter(entry => entry.enabled !== false && entry.targets?.includes('node')).length
             + [...Object.values(preset.skills), ...Object.values(preset.providers)].filter(entry => entry.enabled !== false).length;
         result.hosts = await this.hostStatus(false, receipt.nodeRevision, receipt.revision);
         const nodeReady = result.hosts.length > 0 && result.hosts.every(host => host.state === 'active');
@@ -161,12 +161,12 @@ export class PresetInstaller {
         for (const [id, entry] of Object.entries(preset.packages)) {
             if (entry.enabled === false)
                 continue;
-            for (const runtime of entry.runtimes ?? []) {
+            for (const runtime of entry.targets ?? []) {
                 if (runtime === 'browser') {
                     if (!browserReady)
                         result.pending.push({ kind: 'packages', id, runtime, reason: 'BROWSER_SYNC_REQUIRED' });
                 }
-                else if (!receipt.managedModules.includes(id))
+                else if (!receipt.managedModules.includes(id) && Object.keys(current.prepared.bundles.find(bundle => bundle.manifest.id === id)?.manifest.contributions?.nodeRuntimes ?? {}).length)
                     result.pending.push({ kind: 'packages', id, runtime, reason: 'NODE_HOST_NOT_SUPPORTED' });
                 else if (!nodeReady)
                     result.pending.push({ kind: 'packages', id, runtime, reason: 'HOST_SYNC_REQUIRED' });
@@ -196,7 +196,7 @@ export class PresetInstaller {
         result.ready = result.pending.length === 0;
         return result;
     }
-    async synchronize(receipt, previousRevision) {
+    async synchronize(receipt, previousRevision, replaceSkills) {
         const hosts = await this.hostStatus(true, receipt.nodeRevision, receipt.revision);
         const rejection = hosts.find(host => host.state === 'rejected');
         if (rejection) {
@@ -217,7 +217,7 @@ export class PresetInstaller {
         if (installed.receipt?.revision !== receipt.revision || !installed.preset)
             throw new BundleError('BUNDLE_CONFLICT', 'The selected preset changed before component installation');
         const hasExternal = [...Object.values(installed.preset.skills), ...Object.values(installed.preset.providers)].some(entry => entry.enabled !== false);
-        const components = hasExternal || installed.activation?.bindings['plugins.catalog'] ? await this.componentStatus(true, receipt) : {};
+        const components = hasExternal || installed.activation?.bindings['plugins.catalog'] ? await this.componentStatus(true, receipt, replaceSkills) : {};
         const status = await this.status();
         if (components.error)
             status.warnings.push(`Component installation failed; completed assets retained for retry: ${components.error}`);
@@ -263,7 +263,7 @@ export class PresetInstaller {
     }
     /** Save exact resources and desired selection; activate once after runtime setup, then retry via resume. */
     async stage(source, options = {}) {
-        const accepted = { ...options, ...(options.overrides === undefined ? {} : { overrides: mergePresetDefaults({}, options.overrides) }), ...(options.nodeConfig === undefined ? {} : { nodeConfig: mergePresetDefaults({}, options.nodeConfig) }) };
+        const accepted = { ...options, ...(options.overrides === undefined ? {} : { overrides: mergePresetDefaults({}, options.overrides) }) };
         const current = await this.store.current({ verifyResources: false });
         const revision = presetSelectionRevision(current);
         if (accepted.expectedRevision !== undefined && accepted.expectedRevision !== revision)
@@ -279,11 +279,20 @@ export class PresetInstaller {
             throw new Error('No preset is installed');
         return this.apply(current.receipt.snapshot.source, { ...options, expectedRevision: presetSelectionRevision(current) });
     }
-    async resume(expectedRevision) {
+    async resume(expectedRevision, options = {}) {
         const current = await this.store.current();
         if (!current.receipt || current.receipt.revision !== expectedRevision)
             throw new BundleError('BUNDLE_CONFLICT', 'The installed preset changed before resuming');
-        return this.synchronize(current.receipt, expectedRevision);
+        const names = options.replaceSkills;
+        if (names !== undefined && (!Array.isArray(names) || !names.length || names.length > 256 || new Set(names).size !== names.length || names.some(name => typeof name !== 'string' || !/^[a-z][a-z0-9-]{0,79}$/.test(name) || !current.preset || !Object.hasOwn(current.preset.skills, name) || current.preset.skills[name].enabled === false)))
+            throw new Error('Invalid Skill replacement selection');
+        return this.synchronize(current.receipt, expectedRevision, options.replaceSkills);
+    }
+    async repair(options = {}) {
+        const current = await this.store.current({ verifyResources: false });
+        if (!current.receipt)
+            throw new Error('No preset is installed');
+        return this.resume(current.receipt.revision, options);
     }
     async configure(value) {
         const current = await this.store.current();
@@ -293,7 +302,11 @@ export class PresetInstaller {
         return this.synchronize(receipt, presetSelectionRevision(current));
     }
 }
-export async function runPresetCommand(command, source) {
+export async function runPresetCommand(command, source, options = {}) {
+    if (command !== 'repair' && options.replaceSkills !== undefined)
+        throw new Error('Skill replacements require preset repair');
     const installer = new PresetInstaller();
+    if (command === 'repair')
+        return installer.repair(options);
     return command === 'status' ? installer.status() : command === 'update' ? installer.update() : installer.apply(source);
 }

package/dist/presetStore.d.ts

@@ -1,4 +1,4 @@
-import { type JsonObject, type NodeCapabilityActivation, type ResolvedPreset } from '@mearl/preset';
+import { type JsonObject, type CapabilityActivation, type ResolvedPreset } from '@mearl/preset';
 import { type PreparedBundle, type PreparedPreset, type PresetSnapshot } from '@mearl/preset/bundles';
 export interface PresetInstallReceipt {
     schemaVersion: 1;
@@ -9,13 +9,12 @@ export interface PresetInstallReceipt {
     managedModules: string[];
     nodeSyncRequired: boolean;
     browserSyncRequired?: boolean;
-    nodeConfig: Record<string, JsonObject>;
     overrides: JsonObject;
     revision: string;
 }
 interface SelectionState {
     rawHash: string | null;
-    activation?: NodeCapabilityActivation;
+    activation?: CapabilityActivation;
     receipt?: PresetInstallReceipt;
     prepared?: PreparedPreset;
     preset?: ResolvedPreset;
@@ -36,7 +35,6 @@ export declare class PresetInstallationStore {
     apply(input: Pick<PreparedPreset, 'snapshot' | 'bundles'>, options: {
         expectedRevision: string | null;
         overrides?: JsonObject;
-        nodeConfig?: Record<string, JsonObject>;
         signal?: AbortSignal;
         confirm?: () => Promise<void>;
     }): Promise<PresetInstallReceipt>;

package/dist/presetStore.js

@@ -3,13 +3,13 @@ import { constants, closeSync, fstatSync, lstatSync, linkSync, mkdirSync, openSy
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { withRecordLock } from '@mearl/daemon-core';
-import { mergePresetDefaults, prepareNodeBundleSnapshot, prepareNodeCapabilitySnapshot, verifyNodeCapabilityActivation, validateNodeModuleConfig, resolvePresetModuleConfig, MAX_NODE_SELECTION_BYTES } from '@mearl/preset';
+import { mergePresetDefaults, prepareNodeBundleSnapshot, prepareCapabilitySnapshot, verifyCapabilityActivation, resolveCapabilityConfig, MAX_CAPABILITY_SELECTION_BYTES } from '@mearl/preset';
 import { BundleError, MAX_BROWSER_STORAGE_BYTES, presetRequiresBrowser, validateBundleManifest, verifyPreset, verifyBrowserPreset, verifyPreparedPreset } from '@mearl/preset/bundles';
 const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
 const hashPattern = /^[a-f0-9]{64}$/;
 const MAX_RECEIPT_BYTES = 16 * 1024 * 1024;
 const MAX_OVERRIDES_BYTES = 262_144;
-const POINTER_BYTES = MAX_NODE_SELECTION_BYTES + 128;
+const POINTER_BYTES = MAX_CAPABILITY_SELECTION_BYTES + 128;
 function readBounded(file, limit) {
     const before = lstatSync(file);
     if (!before.isFile() || before.isSymbolicLink() || before.size > limit)
@@ -84,7 +84,7 @@ export class PresetInstallationStore {
         if (!raw)
             return { rawHash: null };
         const rawHash = digest(raw);
-        const activation = await verifyNodeCapabilityActivation(JSON.parse(raw.toString('utf8')));
+        const activation = await verifyCapabilityActivation(JSON.parse(raw.toString('utf8')));
         if (!activation.installationRevision)
             return { rawHash, activation };
         const captured = withRecordLock(this.pointer, () => {
@@ -93,13 +93,12 @@ export class PresetInstallationStore {
             const receipt = JSON.parse(receiptBytes.toString('utf8'));
             const { revision: receiptRevision, ...data } = receipt;
             if (receiptRevision !== activation.installationRevision || digest(JSON.stringify(data)) !== receiptRevision || data.schemaVersion !== 1 ||
-                Object.keys(data).some(key => !['schemaVersion', 'snapshot', 'bundles', 'browserRevision', 'nodeRevision', 'managedModules', 'nodeSyncRequired', 'browserSyncRequired', 'nodeConfig', 'overrides'].includes(key)) || typeof data.nodeSyncRequired !== 'boolean' || (data.browserSyncRequired !== undefined && typeof data.browserSyncRequired !== 'boolean') ||
+                Object.keys(data).some(key => !['schemaVersion', 'snapshot', 'bundles', 'browserRevision', 'nodeRevision', 'managedModules', 'nodeSyncRequired', 'browserSyncRequired', 'overrides'].includes(key)) || typeof data.nodeSyncRequired !== 'boolean' || (data.browserSyncRequired !== undefined && typeof data.browserSyncRequired !== 'boolean') ||
                 data.nodeRevision !== activation.revision || !Array.isArray(data.bundles) || data.bundles.length > 64 ||
                 !Array.isArray(data.managedModules) || new Set(data.managedModules).size !== data.managedModules.length || data.managedModules.some(id => typeof id !== 'string' || !Object.hasOwn(activation.modules, id))) {
                 throw new BundleError('BUNDLE_INTEGRITY', 'Installed preset receipt does not match its selection');
             }
             const acceptedOverrides = overrides(data.overrides);
-            const nodeConfig = validateNodeModuleConfig(data.nodeConfig);
             let total = 0;
             const metadata = data.bundles.map(bundle => {
                 if (Object.keys(bundle).some(key => !['source', 'manifest', 'revision'].includes(key)))
@@ -116,18 +115,18 @@ export class PresetInstallationStore {
                 if (bytes.byteLength !== entry.byteLength || digest(bytes) !== entry.sha256)
                     throw new BundleError('BUNDLE_INTEGRITY', 'Installed Node object is missing or corrupt');
             }
-            return { receipt: { ...receipt, overrides: acceptedOverrides, nodeConfig }, bundles };
+            return { receipt: { ...receipt, overrides: acceptedOverrides }, bundles };
         });
         if (options.verifyResources === false) {
             const graph = await verifyPreset(captured.receipt.snapshot, this.mearlApiVersion);
-            await verifyBrowserPreset({ source: graph.snapshot.source, manifests: graph.snapshot.manifests,
-                bundleRevisions: Object.fromEntries(Object.entries(graph.snapshot.bundleRevisions).filter(([id]) => graph.preset.packages[id].runtimes?.includes('browser'))), revision: captured.receipt.browserRevision }, this.mearlApiVersion);
+            await verifyBrowserPreset({ source: graph.snapshot.source, manifests: graph.snapshot.manifests, packageTargets: graph.snapshot.packageTargets,
+                bundleRevisions: Object.fromEntries(Object.entries(graph.snapshot.bundleRevisions).filter(([id]) => graph.preset.packages[id].targets?.includes('browser'))), revision: captured.receipt.browserRevision }, this.mearlApiVersion);
             return { rawHash, activation, receipt: captured.receipt, preset: graph.preset };
         }
         const prepared = await verifyPreparedPreset({ snapshot: captured.receipt.snapshot, bundles: captured.bundles }, this.mearlApiVersion);
         if (prepared.browser.snapshot.revision !== captured.receipt.browserRevision)
             throw new BundleError('BUNDLE_INTEGRITY', 'Installed browser projection does not match');
-        const selected = await prepareNodeBundleSnapshot(prepared.bundles.filter(bundle => prepared.preset.packages[bundle.manifest.id].runtimes?.includes('node')), 'native-host', this.mearlApiVersion, resolvePresetModuleConfig(mergePresetDefaults(prepared.preset.defaults, captured.receipt.overrides), captured.receipt.nodeConfig));
+        const selected = await prepareNodeBundleSnapshot(prepared.bundles.filter(bundle => prepared.preset.packages[bundle.manifest.id].targets?.includes('node')), 'native-host', this.mearlApiVersion, resolveCapabilityConfig(mergePresetDefaults(prepared.preset.defaults, captured.receipt.overrides)));
         if (Object.keys(selected.snapshot.modules).length !== captured.receipt.managedModules.length || captured.receipt.managedModules.some(id => !Object.hasOwn(selected.snapshot.modules, id)) ||
             Object.entries(selected.snapshot.modules).some(([id, entry]) => JSON.stringify(entry) !== JSON.stringify(activation.modules[id])) ||
             Object.entries(selected.snapshot.bindings).some(([hook, entry]) => JSON.stringify(entry) !== JSON.stringify(activation.bindings[hook])) ||
@@ -139,12 +138,10 @@ export class PresetInstallationStore {
     async apply(input, options) {
         options.signal?.throwIfAborted();
         const acceptedOverrides = options.overrides === undefined ? undefined : overrides(options.overrides);
-        const nodeConfig = options.nodeConfig === undefined ? undefined : validateNodeModuleConfig(options.nodeConfig);
         const [current, prepared] = await Promise.all([this.current({ verifyResources: false }), verifyPreparedPreset(input, this.mearlApiVersion)]);
         if (revision(current) !== options.expectedRevision)
             throw new BundleError('BUNDLE_CONFLICT', 'The installed preset changed');
-        const configured = nodeConfig ?? current.receipt?.nodeConfig ?? Object.fromEntries(Object.entries(current.activation?.modules ?? {}).filter(([, entry]) => entry.config !== undefined).map(([id, entry]) => [id, entry.config]));
-        const selected = await prepareNodeBundleSnapshot(prepared.bundles.filter(bundle => prepared.preset.packages[bundle.manifest.id].runtimes?.includes('node')), 'native-host', this.mearlApiVersion, resolvePresetModuleConfig(mergePresetDefaults(prepared.preset.defaults, acceptedOverrides ?? current.receipt?.overrides ?? {}), configured));
+        const selected = await prepareNodeBundleSnapshot(prepared.bundles.filter(bundle => prepared.preset.packages[bundle.manifest.id].targets?.includes('node')), 'native-host', this.mearlApiVersion, resolveCapabilityConfig(mergePresetDefaults(prepared.preset.defaults, acceptedOverrides ?? current.receipt?.overrides ?? {})));
         const previousManaged = new Set(current.receipt?.managedModules ?? []);
         const unmanaged = Object.fromEntries(Object.entries(current.activation?.modules ?? {}).filter(([id]) => !previousManaged.has(id)));
         for (const entry of Object.values(unmanaged)) {
@@ -157,15 +154,14 @@ export class PresetInstallationStore {
         const bindings = Object.fromEntries(Object.entries(current.activation?.bindings ?? {}).filter(([, entry]) => Object.hasOwn(unmanaged, entry.module)));
         if (Object.keys(selected.snapshot.bindings).some(hook => Object.hasOwn(bindings, hook)))
             throw new BundleError('BUNDLE_CONFLICT', 'A preset hook conflicts with an independently installed Node module');
-        const snapshot = await prepareNodeCapabilitySnapshot({ schemaVersion: 1, modules: { ...unmanaged, ...selected.snapshot.modules }, bindings: { ...bindings, ...selected.snapshot.bindings } });
+        const snapshot = await prepareCapabilitySnapshot({ schemaVersion: 1, modules: { ...unmanaged, ...selected.snapshot.modules }, bindings: { ...bindings, ...selected.snapshot.bindings } });
         const data = {
             schemaVersion: 1, snapshot: prepared.snapshot,
             bundles: prepared.bundles.map(({ source, revision, manifest }) => ({ source, revision, manifest })),
             browserRevision: prepared.browser.snapshot.revision, nodeRevision: snapshot.revision,
             managedModules: Object.keys(selected.snapshot.modules), overrides: acceptedOverrides ?? current.receipt?.overrides ?? {},
-            nodeSyncRequired: Boolean(current.receipt?.nodeSyncRequired || current.receipt?.managedModules.length || Object.values(prepared.preset.packages).some(entry => entry.enabled !== false && entry.runtimes?.includes('node'))),
+            nodeSyncRequired: Boolean(current.receipt?.nodeSyncRequired || current.receipt?.managedModules.length || Object.values(prepared.preset.packages).some(entry => entry.enabled !== false && entry.targets?.includes('node'))),
             browserSyncRequired: Boolean(current.receipt?.browserSyncRequired || presetRequiresBrowser(prepared.preset)),
-            nodeConfig: configured,
         };
         const receipt = { ...data, revision: digest(JSON.stringify(data)) };
         const receiptBytes = JSON.stringify(receipt);
@@ -207,7 +203,7 @@ export class PresetInstallationStore {
         const record = JSON.parse(readBounded(join(this.directory, 'rollback.json'), POINTER_BYTES + 256).toString('utf8'));
         if (record.candidate !== expectedRevision)
             throw new BundleError('BUNDLE_CONFLICT', 'The preset rollback record has changed');
-        const previous = record.previous === null ? undefined : await verifyNodeCapabilityActivation(record.previous);
+        const previous = record.previous === null ? undefined : await verifyCapabilityActivation(record.previous);
         withRecordLock(this.pointer, () => {
             this.assertCurrent(current.rawHash);
             if (previous)
@@ -222,7 +218,7 @@ export class PresetInstallationStore {
         const current = await this.current({ verifyResources: false });
         const raw = optionalFile(join(this.directory, 'rollback.json'), POINTER_BYTES + 256);
         const record = raw && JSON.parse(raw.toString('utf8'));
-        const previous = record?.candidate === current.activation?.installationRevision && record.previous !== null ? await verifyNodeCapabilityActivation(record.previous) : undefined;
+        const previous = record?.candidate === current.activation?.installationRevision && record.previous !== null ? await verifyCapabilityActivation(record.previous) : undefined;
         withRecordLock(this.pointer, () => {
             this.assertCurrent(current.rawHash);
             for (const child of ['blobs', 'objects', 'installations'])

package/dist/skills.js

@@ -4,11 +4,11 @@ import { homedir } from 'node:os';
 import { NodeCapabilityRegistry } from '@mearl/daemon-core/capabilities';
 import { inspectGlobalSkill, readTrackedSkillSources } from './skillSources.js';
 import { PresetInstallationStore } from './presetStore.js';
-import { findExecutable, isExecutable, prependCommandPath, prependNodePath, runCommand, } from '@mearl/daemon-core';
+import { findExecutable, isExecutable, npmExecEnvironment, prependCommandPath, prependNodePath, runCommand, } from '@mearl/daemon-core';
 export const SKILLS_CLI_PACKAGE = 'skills@1.5.0';
 export const MEARL_SKILL_SOURCE = SETUP_VERSION.includes('-beta.')
-    ? `https://github.com/F-loat/mearl/tree/v${SETUP_VERSION}`
-    : 'https://github.com/F-loat/mearl';
+    ? `https://github.com/mearlhq/mearl/tree/v${SETUP_VERSION}`
+    : 'https://github.com/mearlhq/mearl';
 const COMMAND_TIMEOUT_MS = 120_000;
 const ANSI_ESCAPE_PATTERN = new RegExp(String.raw `\u001B\[[0-?]*[ -/]*[@-~]`, 'g');
 export function stripAnsi(value) {
@@ -41,7 +41,7 @@ export function resolveSkillsInvocation(options = {}) {
     return {
         command: npx,
         argsPrefix: ['-y', SKILLS_CLI_PACKAGE],
-        env: prependNodePath(prependCommandPath(npx, env), processExecPath),
+        env: npmExecEnvironment(prependNodePath(prependCommandPath(npx, env), processExecPath)),
     };
 }
 /** Only the selected manager module is needed; browser and Provider factories stay in their hosts. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "3.0.0-beta.5",
+  "version": "3.0.0-beta.7",
   "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",
@@ -68,31 +68,32 @@
   ],
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=20.18.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "commander": "^15.0.0",
-    "extract-zip": "^2.0.1",
+    "commander": "^14.0.3",
     "ws": "^8.18.3",
     "semver": "^7.8.5",
-    "@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"
+    "adm-zip": "^0.6.1",
+    "@mearl/client": "3.0.0-beta.7",
+    "@mearl/provider": "3.0.0-beta.7",
+    "@mearl/daemon-core": "3.0.0-beta.7",
+    "@mearl/preset": "3.0.0-beta.7",
+    "@mearl/browser-core": "3.0.0-beta.7"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",
     "@types/ws": "^8.18.1",
     "typescript": "^5.8.3",
-    "@types/semver": "^7.7.1"
+    "@types/semver": "^7.7.1",
+    "@types/adm-zip": "^0.5.7"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/F-loat/mearl.git",
+    "url": "git+https://github.com/mearlhq/mearl.git",
     "directory": "packages/setup"
   },
   "scripts": {