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

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/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.2",
   "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/client": "3.0.0-beta.2",
+    "@mearl/provider": "3.0.0-beta.2",
+    "@mearl/daemon-core": "3.0.0-beta.2",
+    "@mearl/browser-core": "3.0.0-beta.2",
+    "@mearl/preset": "3.0.0-beta.2"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",