@mearl/setup 3.0.0-beta.1 → 3.0.0-beta.3

package/README.md

@@ -5,20 +5,20 @@
 Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全局安装 setup：
 
 ```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 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: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>
 ```
 
 浏览器 Provider 独立安装和演进。安装后运行 `mearl <providerId>` 查看该版本声明的能力、
 配置和启动参数。
 
-在 Qoder Cloud Agent 环境中，使用 `npx @mearl/setup@beta --qoder-cloud --yes` 选择 Qoder
+在 Qoder Cloud Agent 环境中，使用 `npx --@mearl:registry=https://registry.npmjs.org @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/setup@beta provider <install|update|uninstall> <package|id>
 一个命令安装 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: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
 mearl tabs summary
 ```
 
@@ -45,8 +45,8 @@ Native preset 批次新建的插件注册使用 setup 托管归属，后续通
 已通过其他渠道分发的 skill 或自定义入口，可以直接传入路径注册：
 
 ```bash
-npx @mearl/setup@beta plugin /absolute/path/to/browser-tab-manager
-npx @mearl/setup@beta plugin custom ./skills/custom/entry.mjs
+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
 ```
 
 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/setup@beta plugin uninstall tabs
+npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta plugin uninstall tabs
 ```
 
 若入口位于 `~/.agents/skills/<skill>/`，setup 会先执行
@@ -75,9 +75,9 @@ Provider 由 npm 包分发，但包本身无需暴露 CLI 或安装脚本。setu
 可创建的浏览器类型名称及其表单参数：
 
 ```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
+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
 ```
 
 安装参数接受包名、版本或 dist-tag；更新和卸载可使用 providerId 或完整包名。核心 @mearl 包固定使用公共 npm registry；其余 scope 沿用调用方的包管理器配置，组织 registry 由能力安装引导提供。安装沿用启动 setup 的包管理器，
@@ -88,8 +88,8 @@ npx @mearl/setup@beta provider uninstall example-device
 ## 行为
 
 - Mearl 自有 npm 包的安装和更新固定使用 `https://registry.npmjs.org/`，与最新版本查询使用同一来源；第三方包沿用当前包管理器的源配置。
-- `install` 可以省略；直接执行 `npx @mearl/setup@beta` 等同于 `npx @mearl/setup@beta install`。
-  以选项开头时也默认安装，例如 `npx @mearl/setup@beta --cloud --yes`。
+- `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` 未指定环境时默认 `--local`。
 - `-h` / `--help` 显示帮助，`-v` / `--version` 显示 setup 版本。
 - `update` 和 `uninstall` 未指定环境时，从当前 `PATH` 中的
@@ -137,19 +137,19 @@ npx @mearl/setup@beta provider uninstall example-device
 ## 安装或更新浏览器扩展
 
 ```bash
-npx @mearl/setup@beta extension
+npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta extension
 ```
 
 首次使用时可一次安装完整的本地浏览器环境：
 
 ```bash
-npx @mearl/setup@beta extension --full
+npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta extension --full
 ```
 
 首次安装、旧版 setup 扩展首次迁移，或 Native Host reload 不可用时才需要 CDP。如果
 Chrome 尚未开放 CDP，交互命令会提示打开
 `chrome://inspect/#remote-debugging`、启用远程调试并允许连接，然后等待安装完成。面向人的
-安装指引不要添加 `--yes`。无 TTY 环境使用 `npx @mearl/setup@beta extension --yes`；它只尝试
+安装指引不要添加 `--yes`。无 TTY 环境使用 `npx --@mearl:registry=https://registry.npmjs.org @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/setup@beta update --local`。
+生命周期可重新尝试，也可手动执行 `npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta update --local`。
 
 ## 人工与 Agent 使用
 
@@ -194,41 +194,41 @@ DevTools 面板的设置按钮会显示红点，快捷设置中提供“立即
 
 ```bash
 # 默认安装本地浏览器环境
-npx @mearl/setup
+npx --@mearl:registry=https://registry.npmjs.org @mearl/setup
 
 # 与上一条等价
-npx @mearl/setup@beta install
+npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta install
 
 # Agent / CI 无交互安装
-npx @mearl/setup@beta --yes
+npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta --yes
 
 # 安装云端 Agent 环境
-npx @mearl/setup@beta --cloud
+npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta --cloud
 
 # 同一台机器同时作为本地浏览器宿主和云端 Agent
-npx @mearl/setup@beta --local --cloud
+npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta --local --cloud
 
 # 自动更新当前 PATH 中检测到的全部 Mearl 环境
-npx @mearl/setup@beta update
+npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta update
 
 # 独立安装或更新到最新浏览器扩展
-npx @mearl/setup@beta extension
+npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta extension
 
 # 安装完整本地环境（client、Native Host、Skill 和扩展）
-npx @mearl/setup@beta extension --full
+npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta extension --full
 
 # 只卸载本地环境
-npx @mearl/setup@beta uninstall --local
+npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta uninstall --local
 
 # 自动检测并无交互卸载
-npx @mearl/setup@beta uninstall --yes
+npx --@mearl:registry=https://registry.npmjs.org @mearl/setup@beta uninstall --yes
 
 # 卸载环境，并清理全部 CLI 插件与 Provider
-npx @mearl/setup@beta uninstall --full
+npx --@mearl:registry=https://registry.npmjs.org @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
+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
 ```
 
 原有 Mearl 环境包的 npm/npx 安装方式和 CLI 保持可用；setup 是统一的便利入口。

package/dist/cli.js

@@ -177,7 +177,7 @@ function printHelp() {
     const output = `Mearl Setup v${SETUP_VERSION}
 
 Usage:
-  npx @mearl/setup [command] [options]
+  npx --@mearl:registry=https://registry.npmjs.org @mearl/setup [command] [options]
 
 Environment commands:
   install [options]               Install an environment (default command; target: local)
@@ -221,15 +221,15 @@ General options:
   --help, -h                      Show this help
 
 Examples:
-  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));
+  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));
 }
 async function runSetupLifecycle(options, dependencies) {
     let preset;

package/dist/lifecycle.js

@@ -236,7 +236,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/setup');
+        writeLine('Run: npx --@mearl:registry=https://registry.npmjs.org @mearl/setup');
         return false;
     }
     if (options.operation === 'update') {

package/dist/plugin.js

@@ -1,7 +1,8 @@
 import { existsSync, mkdirSync, readdirSync, readlinkSync, realpathSync, rmdirSync, statSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { assertPluginName, findPluginDirectoryEntry, readOfficialPluginCatalog, findPluginEntry, findPluginRegistration, listPluginNames, loadPlugin, OFFICIAL_PLUGIN_MANAGER, registerPlugin, resolvePluginEntry, unregisterPlugin, } from '@mearl/client/plugin';
+import { assertPluginName, findPluginDirectoryEntry, skillManifestPath, readOfficialPluginCatalog, findPluginEntry, findPluginRegistration, listPluginNames, loadPlugin, OFFICIAL_PLUGIN_MANAGER, registerPlugin, resolvePluginEntry, unregisterPlugin, } from '@mearl/client/plugin';
+import { preserveSkillDisabled } from './skillSources.js';
 import { claimPresetInstallation } from './presetInstallationLease.js';
 import { ensurePluginRuntime } from './pluginRuntime.js';
 import { captureSkillsCli, parseInstalledSkills, stripAnsi } from './skills.js';
@@ -52,8 +53,22 @@ export async function ensureOfficialPlugin(name, runner = runCommand) {
     const definition = accepted?.plugins[name];
     if (!definition)
         throw new Error(`未知官方插件: ${name}`);
-    if (findPluginRegistration(name))
-        return 'existing';
+    const existing = findPluginRegistration(name);
+    if (existing) {
+        if (!accepted.selection || existing.managedBy !== OFFICIAL_PLUGIN_MANAGER)
+            return 'existing';
+        const cli = await captureSkillsCli({ runCommand: runner });
+        if (!cli || cli.selection?.path !== accepted.selection.path || cli.selection.sha256 !== accepted.selection.sha256)
+            throw new Error('PLUGIN_CATALOG_SELECTION_CHANGED');
+        const declaration = cli.managedSkills[definition.skill];
+        if (!declaration?.source || declaration.source !== definition.installArgs[0])
+            throw new Error('PLUGIN_CATALOG_SKILL_UNDECLARED');
+        const status = cli.inspectGlobal(declaration.source, definition.skill, declaration.version, { migrateFrom: declaration.migrateFrom });
+        if (status.state === 'ready')
+            return 'existing';
+        if (status.state === 'conflict')
+            throw new Error(`${status.reason}: ${definition.skill}`);
+    }
     const lease = claimPresetInstallation();
     try {
         return await withOwnedCommands(lease.lifecycle, async () => {
@@ -276,13 +291,22 @@ export async function installPlugins(args, runner = runCommand, options = {}) {
         if (status.state !== 'ready' && (registered || status.state !== 'registration'))
             throw new Error(`${status.reason}: ${options.expectedSkill}`);
     };
-    if (options.expectedSkill && declaration) {
-        const status = cli.inspectGlobal(declaration.source, options.expectedSkill, declaration.version);
+    const assertSource = () => {
+        if (!options.expectedSkill || !declaration)
+            return;
+        const status = cli.inspectGlobal(declaration.source, options.expectedSkill, declaration.version, {
+            migrateFrom: options.registrationManagedBy === OFFICIAL_PLUGIN_MANAGER ? declaration.migrateFrom : undefined,
+        });
         if (status.state === 'conflict')
             throw new Error(`${status.reason}: ${options.expectedSkill}`);
-    }
+    };
+    assertSource();
     await options.confirm?.();
-    const installed = await cli.run(['add', ...args, '--global'], { tee: true });
+    assertSource();
+    const runInstall = () => cli.run(['add', ...args, '--global'], { tee: true });
+    const installed = await (options.expectedSkill
+        ? preserveSkillDisabled(join(homedir(), '.agents', 'skills', options.expectedSkill), runInstall)
+        : runInstall());
     if (installed.code !== 0)
         return installed.code;
     await options.confirm?.();
@@ -307,7 +331,7 @@ export async function installPlugins(args, runner = runCommand, options = {}) {
     }
     const plugins = new Map();
     for (const skillPath of paths) {
-        if (!statSync(join(skillPath, 'SKILL.md')).isFile())
+        if (!statSync(skillManifestPath(skillPath) ?? join(skillPath, 'SKILL.md')).isFile())
             throw new Error(`安装结果缺少 SKILL.md: ${skillPath}`);
         const entry = findPluginDirectoryEntry(skillPath);
         if (!entry)

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/setup${SETUP_VERSION.includes('-beta.') ? '@' + SETUP_VERSION : ''}`;
+export const SETUP_COMMAND = `npx --@mearl:registry=https://registry.npmjs.org @mearl/setup${SETUP_VERSION.includes('-beta.') ? '@' + SETUP_VERSION : ''}`;

package/dist/skillSourceReceipts.d.ts

@@ -0,0 +1,25 @@
+export type SkillSourceScope = 'global' | 'project';
+export interface TrackedSkillSource {
+    name: string;
+    source: string;
+    scope: SkillSourceScope;
+    ref?: string;
+    skillPath?: string;
+    sourceType?: string;
+    expectedHash?: string;
+    hashKind: 'git-tree' | 'folder';
+}
+export interface SourceOptions {
+    env?: NodeJS.ProcessEnv;
+    homeDirectory?: string;
+}
+export declare function readTrackedSkillSources(scope: SkillSourceScope, cwd?: string, options?: SourceOptions): TrackedSkillSource[];
+/** Custom source kinds require their installed backend, even if they use owner/repo syntax. */
+export declare function isPublicSkillSource(source: TrackedSkillSource): boolean;
+export declare function gitSource(source: string, ref?: string): {
+    repository: string;
+    ref?: string;
+    subdirectory?: string;
+};
+/** Compare the manager's existing source receipt; no network access or second lockfile. */
+export declare function matchesTrackedSkillSource(requested: string, tracked: TrackedSkillSource, normalize?: (source: string, sourceType?: string) => string): boolean;

package/dist/skillSourceReceipts.js

@@ -0,0 +1,94 @@
+import { readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+function lockFile(scope, cwd, options) {
+    const env = options.env ?? process.env;
+    return scope === 'project' ? join(cwd, 'skills-lock.json') : env.XDG_STATE_HOME ? join(env.XDG_STATE_HOME, 'skills', '.skill-lock.json') : join(options.homeDirectory ?? homedir(), '.agents', '.skill-lock.json');
+}
+export function readTrackedSkillSources(scope, cwd, options = {}) {
+    const file = lockFile(scope, cwd, options);
+    let text;
+    try {
+        if (statSync(file).size > 4 * 1024 * 1024)
+            throw new Error('Skill source lock exceeds 4 MiB');
+        text = readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const lock = JSON.parse(text);
+    if (!lock || !lock.skills || typeof lock.skills !== 'object' || Array.isArray(lock.skills))
+        throw new Error('Invalid Skills source lock');
+    return Object.entries(lock.skills).flatMap(([name, entry]) => {
+        if (!entry || typeof entry !== 'object' || entry.sourceType === 'node_modules')
+            return [];
+        if (!name || name === '.' || name === '..' || /[\\/\0\r\n]/.test(name))
+            throw new Error('Invalid tracked Skill name');
+        const source = typeof entry.sourceUrl === 'string' ? entry.sourceUrl : entry.source;
+        if (typeof source !== 'string' || !source.trim())
+            return [];
+        if (source.length > 4096 || /[\0\r\n]/.test(source))
+            throw new Error('Invalid tracked Skill source');
+        const expectedHash = scope === 'global' ? entry.skillFolderHash : entry.computedHash;
+        return [{ name, source, scope, ...(typeof entry.sourceType === 'string' ? { sourceType: entry.sourceType } : {}), ...(typeof entry.ref === 'string' ? { ref: entry.ref } : {}), ...(typeof entry.skillPath === 'string' ? { skillPath: entry.skillPath } : {}), ...(typeof expectedHash === 'string' && expectedHash ? { expectedHash } : {}), hashKind: scope === 'global' && typeof expectedHash === 'string' && /^[a-f0-9]{40}$/.test(expectedHash) ? 'git-tree' : 'folder' }];
+    });
+}
+/** Custom source kinds require their installed backend, even if they use owner/repo syntax. */
+export function isPublicSkillSource(source) {
+    return source.sourceType === undefined || ['github', 'gitlab', 'git', 'local', 'well-known'].includes(source.sourceType);
+}
+export function gitSource(source, ref) {
+    if (/^[\w.-]+\/[\w.-]+$/.test(source))
+        return { repository: `https://github.com/${source}.git`, ...(ref ? { ref } : {}) };
+    if (/^[\w.-]+@[\w.-]+:[^\s]+$/.test(source))
+        return { repository: source, ...(ref ? { ref } : {}) };
+    const url = new URL(source);
+    if (!['https:', 'http:', 'ssh:', 'git:', 'file:'].includes(url.protocol) || url.password || (url.username && url.protocol !== 'ssh:') || url.search || url.hash)
+        throw new Error('Skill source is not a supported Git repository');
+    if (url.hostname === 'github.com' && !url.port) {
+        const parts = url.pathname.split('/').filter(Boolean);
+        if (parts.length >= 2)
+            return { repository: `https://github.com/${parts[0]}/${parts[1].replace(/\.git$/, '')}.git`, ...(ref || (['tree', 'blob'].includes(parts[2]) && parts[3]) ? { ref: ref || decodeURIComponent(parts[3]) } : {}), ...(['tree', 'blob'].includes(parts[2]) && parts.length > 4 ? { subdirectory: decodeURIComponent(parts.slice(4).join('/')).replace(/\/SKILL\.md$/, '') } : {}) };
+    }
+    return { repository: url.href, ...(ref ? { ref } : {}) };
+}
+/** Compare the manager's existing source receipt; no network access or second lockfile. */
+export function matchesTrackedSkillSource(requested, tracked, normalize = source => source) {
+    const location = (source, ref, sourceType) => {
+        const value = normalize(source, sourceType);
+        if (typeof value !== 'string' || !value || value.length > 8192 || /[\0\r\n]/.test(value))
+            throw new Error('Invalid normalized Skill source');
+        const hash = value.indexOf('#');
+        const fragment = hash < 0 ? undefined : value.slice(hash + 1);
+        const plain = hash < 0 ? value : value.slice(0, hash);
+        const parsed = isAbsolute(plain) ? { repository: plain, ref: ref ?? fragment } : gitSource(plain, ref ?? fragment);
+        let repository = parsed.repository;
+        if (repository.startsWith('file:'))
+            repository = fileURLToPath(repository);
+        if (isAbsolute(repository))
+            repository = resolve(repository);
+        else {
+            const ssh = repository.match(/^[\w.-]+@([\w.-]+):(.+)$/);
+            const url = new URL(ssh ? `ssh://${ssh[1]}/${ssh[2]}` : repository);
+            // Authentication transport is independent of the repository's identity.
+            repository = `${url.hostname.toLowerCase()}${url.port ? ':' + url.port : ''}/${url.pathname.replace(/^\/+|\/+$/g, '').replace(/\.git$/, '')}`;
+        }
+        return { ...parsed, repository, ref: parsed.ref || undefined };
+    };
+    try {
+        const expected = location(requested);
+        const actual = location(tracked.source, tracked.ref, tracked.sourceType);
+        if (expected.repository !== actual.repository || expected.ref !== actual.ref)
+            return false;
+        if (!expected.subdirectory)
+            return true;
+        const path = (tracked.skillPath ?? actual.subdirectory ?? '').replace(/(?:^|\/)SKILL\.md$/, '').replace(/\/+$/, '');
+        return path === expected.subdirectory || path.startsWith(expected.subdirectory + '/');
+    }
+    catch {
+        return normalize(requested) === normalize(tracked.source, tracked.sourceType) && !tracked.ref;
+    }
+}

package/dist/skillSources.d.ts

@@ -1,24 +1,7 @@
 import { type CommandRunner } from '@mearl/daemon-core';
-export type SkillSourceScope = 'global' | 'project';
-export interface TrackedSkillSource {
-    name: string;
-    source: string;
-    scope: SkillSourceScope;
-    ref?: string;
-    skillPath?: string;
-    sourceType?: string;
-    expectedHash?: string;
-    hashKind: 'git-tree' | 'folder';
-}
-interface SourceOptions {
-    env?: NodeJS.ProcessEnv;
-    homeDirectory?: string;
-}
-export declare function readTrackedSkillSources(scope: SkillSourceScope, cwd?: string, options?: SourceOptions): TrackedSkillSource[];
-/** Custom source kinds require their installed backend, even if they use owner/repo syntax. */
-export declare function isPublicSkillSource(source: TrackedSkillSource): boolean;
-/** Compare the manager's existing source receipt; no network access or second lockfile. */
-export declare function matchesTrackedSkillSource(requested: string, tracked: TrackedSkillSource, normalize?: (source: string, sourceType?: string) => string): boolean;
+import { readTrackedSkillSources, type SourceOptions, type SkillSourceScope, type TrackedSkillSource } from './skillSourceReceipts.js';
+export { isPublicSkillSource, matchesTrackedSkillSource, readTrackedSkillSources } from './skillSourceReceipts.js';
+export type { SkillSourceScope, TrackedSkillSource } from './skillSourceReceipts.js';
 /** Matches the public Skills folder hash without writing to the installed Skill. */
 export declare function hashSkillDirectory(directory: string, ignoreRuntimeFiles?: boolean): Promise<string>;
 /** Checks source content in a temporary checkout; never invokes the mutating Skills `check` alias. */
@@ -31,16 +14,18 @@ export declare function checkTrackedSkillUpdates(options?: SourceOptions & {
     scope: SkillSourceScope;
 }>>;
 export interface SkillInstallationStatus {
-    state: 'ready' | 'missing' | 'version' | 'registration' | 'conflict';
+    state: 'ready' | 'missing' | 'version' | 'registration' | 'migration' | 'conflict';
     reason?: string;
 }
 /** Developer links keep their Git checkout as the source receipt without changing a manager's lock. */
 export declare function readLinkedSkillSource(directory: string, name: string): TrackedSkillSource | undefined;
+/** Keep the user's disabled state when an installer replaces the Skill directory. */
+export declare function preserveSkillDisabled<T>(directory: string, operation: () => Promise<T>): Promise<T>;
 /** CLI and Agent readiness use the same source, manifest and registration evidence. */
 export declare function inspectGlobalSkill(source: string, name: string, version?: string, options?: {
     homeDirectory?: string;
     readSources?: typeof readTrackedSkillSources;
     externalManager?: boolean;
+    migrateFrom?: readonly string[];
     normalizeSource?: (source: string, sourceType?: string) => string;
 }): SkillInstallationStatus;
-export {};

package/dist/skillSources.js

@@ -1,104 +1,15 @@
 import { createHash } from 'node:crypto';
 import { mkdtemp, readFile, readdir, realpath, rm, stat } from 'node:fs/promises';
-import { readFileSync, statSync, lstatSync, realpathSync } from 'node:fs';
+import { lstatSync, realpathSync, renameSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { homedir, tmpdir } from 'node:os';
-import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { runCommand } from '@mearl/daemon-core';
 import { satisfies, valid } from 'semver';
-import { DISABLED_SKILL_MANIFEST, findPluginDirectoryEntry, findPluginRegistration, listPluginNames, OFFICIAL_PLUGIN_MANAGER, pluginRegistrationNeedsRefresh, readInstalledSkillMetadata } from '@mearl/client/plugin';
+import { DISABLED_SKILL_MANIFEST, getSkillEnabled, findPluginDirectoryEntry, findPluginRegistration, listPluginNames, OFFICIAL_PLUGIN_MANAGER, pluginRegistrationNeedsRefresh, readInstalledSkillMetadata } from '@mearl/client/plugin';
 import { existsSync } from 'node:fs';
-function lockFile(scope, cwd, options) {
-    const env = options.env ?? process.env;
-    return scope === 'project' ? join(cwd, 'skills-lock.json') : env.XDG_STATE_HOME ? join(env.XDG_STATE_HOME, 'skills', '.skill-lock.json') : join(options.homeDirectory ?? homedir(), '.agents', '.skill-lock.json');
-}
-export function readTrackedSkillSources(scope, cwd, options = {}) {
-    const file = lockFile(scope, cwd, options);
-    let text;
-    try {
-        if (statSync(file).size > 4 * 1024 * 1024)
-            throw new Error('Skill source lock exceeds 4 MiB');
-        text = readFileSync(file, 'utf8');
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return [];
-        throw error;
-    }
-    const lock = JSON.parse(text);
-    if (!lock || !lock.skills || typeof lock.skills !== 'object' || Array.isArray(lock.skills))
-        throw new Error('Invalid Skills source lock');
-    return Object.entries(lock.skills).flatMap(([name, entry]) => {
-        if (!entry || typeof entry !== 'object' || entry.sourceType === 'node_modules')
-            return [];
-        if (!name || name === '.' || name === '..' || /[\\/\0\r\n]/.test(name))
-            throw new Error('Invalid tracked Skill name');
-        const source = typeof entry.sourceUrl === 'string' ? entry.sourceUrl : entry.source;
-        if (typeof source !== 'string' || !source.trim())
-            return [];
-        if (source.length > 4096 || /[\0\r\n]/.test(source))
-            throw new Error('Invalid tracked Skill source');
-        const expectedHash = scope === 'global' ? entry.skillFolderHash : entry.computedHash;
-        return [{ name, source, scope, ...(typeof entry.sourceType === 'string' ? { sourceType: entry.sourceType } : {}), ...(typeof entry.ref === 'string' ? { ref: entry.ref } : {}), ...(typeof entry.skillPath === 'string' ? { skillPath: entry.skillPath } : {}), ...(typeof expectedHash === 'string' && expectedHash ? { expectedHash } : {}), hashKind: scope === 'global' && typeof expectedHash === 'string' && /^[a-f0-9]{40}$/.test(expectedHash) ? 'git-tree' : 'folder' }];
-    });
-}
-/** Custom source kinds require their installed backend, even if they use owner/repo syntax. */
-export function isPublicSkillSource(source) {
-    return source.sourceType === undefined || ['github', 'gitlab', 'git', 'local', 'well-known'].includes(source.sourceType);
-}
-function gitSource(source, ref) {
-    if (/^[\w.-]+\/[\w.-]+$/.test(source))
-        return { repository: `https://github.com/${source}.git`, ...(ref ? { ref } : {}) };
-    if (/^[\w.-]+@[\w.-]+:[^\s]+$/.test(source))
-        return { repository: source, ...(ref ? { ref } : {}) };
-    const url = new URL(source);
-    if (!['https:', 'http:', 'ssh:', 'git:', 'file:'].includes(url.protocol) || url.password || (url.username && url.protocol !== 'ssh:') || url.search || url.hash)
-        throw new Error('Skill source is not a supported Git repository');
-    if (url.hostname === 'github.com' && !url.port) {
-        const parts = url.pathname.split('/').filter(Boolean);
-        if (parts.length >= 2)
-            return { repository: `https://github.com/${parts[0]}/${parts[1].replace(/\.git$/, '')}.git`, ...(ref || (['tree', 'blob'].includes(parts[2]) && parts[3]) ? { ref: ref || decodeURIComponent(parts[3]) } : {}), ...(['tree', 'blob'].includes(parts[2]) && parts.length > 4 ? { subdirectory: decodeURIComponent(parts.slice(4).join('/')).replace(/\/SKILL\.md$/, '') } : {}) };
-    }
-    return { repository: url.href, ...(ref ? { ref } : {}) };
-}
-/** Compare the manager's existing source receipt; no network access or second lockfile. */
-export function matchesTrackedSkillSource(requested, tracked, normalize = source => source) {
-    const location = (source, ref, sourceType) => {
-        const value = normalize(source, sourceType);
-        if (typeof value !== 'string' || !value || value.length > 8192 || /[\0\r\n]/.test(value))
-            throw new Error('Invalid normalized Skill source');
-        const hash = value.indexOf('#');
-        const fragment = hash < 0 ? undefined : value.slice(hash + 1);
-        const plain = hash < 0 ? value : value.slice(0, hash);
-        const parsed = isAbsolute(plain) ? { repository: plain, ref: ref ?? fragment } : gitSource(plain, ref ?? fragment);
-        let repository = parsed.repository;
-        if (repository.startsWith('file:'))
-            repository = fileURLToPath(repository);
-        if (isAbsolute(repository))
-            repository = resolve(repository);
-        else {
-            const ssh = repository.match(/^[\w.-]+@([\w.-]+):(.+)$/);
-            const url = new URL(ssh ? `ssh://${ssh[1]}/${ssh[2]}` : repository);
-            // Authentication transport is independent of the repository's identity.
-            repository = `${url.hostname.toLowerCase()}${url.port ? ':' + url.port : ''}/${url.pathname.replace(/^\/+|\/+$/g, '').replace(/\.git$/, '')}`;
-        }
-        return { ...parsed, repository, ref: parsed.ref || undefined };
-    };
-    try {
-        const expected = location(requested);
-        const actual = location(tracked.source, tracked.ref, tracked.sourceType);
-        if (expected.repository !== actual.repository || expected.ref !== actual.ref)
-            return false;
-        if (!expected.subdirectory)
-            return true;
-        const path = (tracked.skillPath ?? actual.subdirectory ?? '').replace(/(?:^|\/)SKILL\.md$/, '').replace(/\/+$/, '');
-        return path === expected.subdirectory || path.startsWith(expected.subdirectory + '/');
-    }
-    catch {
-        return normalize(requested) === normalize(tracked.source, tracked.sourceType) && !tracked.ref;
-    }
-}
+import { gitSource, isPublicSkillSource, matchesTrackedSkillSource, readTrackedSkillSources } from './skillSourceReceipts.js';
+export { isPublicSkillSource, matchesTrackedSkillSource, readTrackedSkillSources } from './skillSourceReceipts.js';
 function skillName(text) {
     return text.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1].match(/^name:\s*["']?([^"'\r\n]+?)["']?\s*$/m)?.[1]?.trim();
 }
@@ -237,6 +148,35 @@ export function readLinkedSkillSource(directory, name) {
         return undefined;
     }
 }
+/** Keep the user's disabled state when an installer replaces the Skill directory. */
+export async function preserveSkillDisabled(directory, operation) {
+    const disabled = getSkillEnabled(directory) === false;
+    try {
+        return await operation();
+    }
+    finally {
+        if (disabled && existsSync(join(directory, 'SKILL.md')))
+            renameSync(join(directory, 'SKILL.md'), join(directory, DISABLED_SKILL_MANIFEST));
+    }
+}
+function canonicalPath(path) {
+    const absolute = resolve(path);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        const parent = dirname(absolute);
+        return parent === absolute ? absolute : join(canonicalPath(parent), basename(absolute));
+    }
+}
+function hasOnlySetupRegistrations(directory) {
+    const contains = (root, entry) => {
+        const path = relative(root, entry);
+        return path !== '' && path !== '..' && !path.startsWith('..' + sep) && !isAbsolute(path);
+    };
+    const registrations = listPluginNames().flatMap(name => findPluginRegistration(name) ?? []).filter(registration => contains(resolve(directory), resolve(registration.entry)) || contains(canonicalPath(directory), canonicalPath(registration.entry)));
+    return registrations.length > 0 && registrations.every(registration => registration.managedBy === OFFICIAL_PLUGIN_MANAGER);
+}
 /** CLI and Agent readiness use the same source, manifest and registration evidence. */
 export function inspectGlobalSkill(source, name, version, options = {}) {
     if (!source.trim() || !name || name === '.' || name === '..' || /[\\/\0\r\n]/.test(name))
@@ -244,10 +184,17 @@ export function inspectGlobalSkill(source, name, version, options = {}) {
     const directory = join(options.homeDirectory ?? homedir(), '.agents', 'skills', name);
     if (existsSync(join(directory, 'SKILL.md')) && existsSync(join(directory, DISABLED_SKILL_MANIFEST)))
         return { state: 'conflict', reason: 'SKILL_MANIFEST_CONFLICT' };
-    const tracked = (options.readSources ?? readTrackedSkillSources)('global', undefined, { homeDirectory: options.homeDirectory }).find(entry => entry.name === name)
+    const receipt = (options.readSources ?? readTrackedSkillSources)('global', undefined, { homeDirectory: options.homeDirectory }).find(entry => entry.name === name);
+    const tracked = receipt
         ?? (!/(?:#|\/(?:tree|blob)\/)/.test(source) ? readLinkedSkillSource(directory, name) : undefined);
-    if (tracked && ((!options.externalManager && !isPublicSkillSource(tracked)) || !matchesTrackedSkillSource(source, tracked, options.normalizeSource)))
+    if (tracked && ((!options.externalManager && !isPublicSkillSource(tracked)) || !matchesTrackedSkillSource(source, tracked, options.normalizeSource))) {
+        const metadata = readInstalledSkillMetadata(directory);
+        if (receipt && (options.externalManager || isPublicSkillSource(receipt)) && metadata?.name === name &&
+            options.migrateFrom?.some(previous => matchesTrackedSkillSource(previous, receipt, options.normalizeSource)) && hasOnlySetupRegistrations(directory)) {
+            return { state: 'migration', reason: 'SKILL_SOURCE_MIGRATION_REQUIRED' };
+        }
         return { state: 'conflict', reason: 'SKILL_SOURCE_CONFLICT' };
+    }
     const metadata = readInstalledSkillMetadata(directory);
     if (!metadata)
         return { state: 'missing', reason: 'SKILL_NOT_INSTALLED' };

package/dist/skills.js

@@ -59,9 +59,11 @@ export async function captureSkillsCli(options = {}) {
     const managedSkills = Object.fromEntries(Object.entries(current.preset?.skills ?? {}).filter(([, entry]) => entry.enabled !== false));
     const backend = registry.get('skills.manager')?.();
     if (backend !== undefined) {
+        if (backend?.readSources !== undefined && typeof backend.readSources !== 'function')
+            throw new Error('Invalid Skill source reader');
         if (!backend || typeof backend.id !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(backend.id) || typeof backend.cli !== 'function')
             throw new Error('The selected Skill manager requires a preset update for CLI operations');
-        return { id: backend.id, managedSkills, selection, inspectGlobal: (source, name, version) => inspectGlobalSkill(source, name, version, { externalManager: true, normalizeSource: backend.normalizeSource, readSources }), run: async (args, settings) => {
+        return { id: backend.id, managedSkills, selection, inspectGlobal: (source, name, version, inspection) => inspectGlobalSkill(source, name, version, { migrateFrom: inspection?.migrateFrom, externalManager: true, normalizeSource: backend.normalizeSource, readSources: backend.readSources ?? readSources }), run: async (args, settings) => {
                 const result = await backend.cli([...args], settings);
                 if (!result || !Number.isInteger(result.code) || typeof result.stdout !== 'string' || typeof result.stderr !== 'string')
                     throw new Error('Invalid Skill manager CLI result');
@@ -71,7 +73,7 @@ export async function captureSkillsCli(options = {}) {
     const invocation = resolveSkillsInvocation(options);
     if (!invocation)
         return undefined;
-    return { id: 'skills', managedSkills, selection, inspectGlobal: (source, name, version) => inspectGlobalSkill(source, name, version, { readSources }), run: (args, settings) => runner(invocation.command, [...invocation.argsPrefix, ...args], { ...settings, env: invocation.env }) };
+    return { id: 'skills', managedSkills, selection, inspectGlobal: (source, name, version, inspection) => inspectGlobalSkill(source, name, version, { migrateFrom: inspection?.migrateFrom, readSources }), run: (args, settings) => runner(invocation.command, [...invocation.argsPrefix, ...args], { ...settings, env: invocation.env }) };
 }
 export function parseInstalledSkills(output) {
     const value = JSON.parse(stripAnsi(output).trim());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0-beta.3",
   "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",
@@ -45,6 +45,10 @@
     "./preset": {
       "types": "./dist/preset.d.ts",
       "import": "./dist/preset.js"
+    },
+    "./skill-source-receipts": {
+      "types": "./dist/skillSourceReceipts.d.ts",
+      "import": "./dist/skillSourceReceipts.js"
     }
   },
   "bin": {
@@ -74,11 +78,11 @@
     "extract-zip": "^2.0.1",
     "ws": "^8.18.3",
     "semver": "^7.8.5",
-    "@mearl/preset": "3.0.0-beta.1",
-    "@mearl/daemon-core": "3.0.0-beta.1",
-    "@mearl/client": "3.0.0-beta.1",
-    "@mearl/provider": "3.0.0-beta.1",
-    "@mearl/browser-core": "3.0.0-beta.1"
+    "@mearl/daemon-core": "3.0.0-beta.3",
+    "@mearl/provider": "3.0.0-beta.3",
+    "@mearl/browser-core": "3.0.0-beta.3",
+    "@mearl/client": "3.0.0-beta.3",
+    "@mearl/preset": "3.0.0-beta.3"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",