@mearl/setup 3.0.1 → 3.0.2

package/README.en.md

@@ -19,7 +19,8 @@ npx @mearl/setup plugin install <skills add arguments...>
 npx @mearl/setup plugin uninstall <name>
 npx @mearl/setup provider <install|update|uninstall> <package|id>
 npx @mearl/setup profile install <source> [--browser <id-or-name>]
-npx @mearl/setup preset repair [--replace-skill <name> ...]
+npx @mearl/setup preset apply [source]
+npx @mearl/setup preset <update|status|uninstall>
 ```
 
 Browser Providers install and evolve independently. After installation, run `mearl <providerId>` to inspect that version's capabilities,
@@ -52,14 +53,16 @@ The installation host's local plugin catalog determines preset-managed capabilit
 
 New registrations created by Native preset batches are setup-managed and retain that ownership through Agent updates. Existing user registrations in the same directory and custom user aliases retain their ownership. Managed removal encountering user aliases sharing a Skill removes only managed registrations and keeps Skill files.
 
-GUI and CLI share the preset installer and override rules. If a saved installation is incomplete, `preset repair` retries accepted local resources without redownloading the preset or implicitly replacing conflicting sources. Explicit repeated `--replace-skill` authorizes replacing those Skills' sources or same-name plugin registrations for this invocation:
+GUI and CLI share the preset installer and override rules. `preset apply` accepts a URL or local file path. Omitting the source retries from the saved snapshot. `preset update` rereads the current source. Repeat `--replace-skill` during a retry to authorize replacing those Skill sources or same-name plugin registrations for this invocation.
 
 ```bash
-npx @mearl/setup preset repair --replace-skill example-skill --replace-skill another-skill
+npx @mearl/setup preset apply --replace-skill example-skill --replace-skill another-skill
 ```
 
 Already installed Skills receive registration repair only; source conflicts reinstall. Unlisted conflicts still block installation, and undeclared tool names or changed installation identities are rejected. Replacement authorization does not persist into later repairs or automatic updates. Missing browser permissions still require extension authorization. Output uses preset JSON: ready exits `0`, pending components `3`, installation failure `1`, and invalid arguments `2`.
 
+Run `preset uninstall` to remove the local preset and matching selections in connected extensions. Removal clears preset-managed capability packages and setup-managed registrations in the selected plugin catalog. It preserves independent capabilities, Skill files, Providers, and browser permissions. [See what preset removal covers](../../docs/preset-installation.en.md)
+
 Automatic registration defaults to the installation directory name; an entry can declare `name` for a shorter command.
 Reinstallation refreshes same-name bindings. JavaScript entries must default-export `register(app)`; Python entries must export a `register(app)` function. See the
 [plugin runtime contract](../../docs/plugin-runtime.en.md).

package/README.md

@@ -19,7 +19,8 @@ npx @mearl/setup plugin install <skills add 参数...>
 npx @mearl/setup plugin uninstall <name>
 npx @mearl/setup provider <install|update|uninstall> <package|id>
 npx @mearl/setup profile install <来源> [--browser <标识或名称>]
-npx @mearl/setup preset repair [--replace-skill <name> ...]
+npx @mearl/setup preset apply [来源]
+npx @mearl/setup preset <update|status|uninstall>
 ```
 
 浏览器 Provider 独立安装和演进。安装后运行 `mearl <providerId>` 查看该版本声明的能力、
@@ -52,14 +53,16 @@ mearl tabs summary
 
 Native preset 批次新建的插件注册使用 setup 托管归属，后续通过 Agent 更新仍保留该归属；同目录已有的用户注册保持原归属，自定义用户别名也会保留。托管卸载遇到用户别名共用同一 Skill 时，只清除托管注册并保留 Skill 文件。
 
-GUI 和 CLI 使用同一套 preset 安装器及覆盖规则。已保存的安装尚未完成时，运行 `preset repair` 从接受的本地资源重试，不重新下载 preset，也不隐式覆盖冲突来源。显式重复指定 `--replace-skill` 即授权本次替换这些 Skill 的来源或同名旧插件注册：
+GUI 和 CLI 使用同一套 preset 安装器及覆盖规则。`preset apply` 接受 URL 或本地文件路径。省略来源时使用已保存的快照重试。`preset update` 重新读取当前来源。重试时可显式重复指定 `--replace-skill`，授权本次替换这些 Skill 的来源或同名旧插件注册。
 
 ```bash
-npx @mearl/setup preset repair --replace-skill example-skill --replace-skill another-skill
+npx @mearl/setup preset apply --replace-skill example-skill --replace-skill another-skill
 ```
 
 已安装的 Skill 仅修复注册；来源冲突项重新安装。未列出的冲突仍会阻止安装，声明外的工具名与变更后的安装身份也会被拒绝。覆盖授权不会保留到后续普通修复或自动更新。缺少浏览器权限时仍需在扩展中授权。输出沿用 preset JSON，已就绪退出 `0`、仍有待完成项退出 `3`、安装失败退出 `1`，无效参数退出 `2`。
 
+运行 `preset uninstall` 清理本机 preset 和匹配的已连接扩展。卸载会移除 preset 托管的能力包和当前目录中由 setup 托管的插件注册，保留独立安装的能力、Skill 文件、Provider 和浏览器权限。[查看卸载范围](../../docs/preset-installation.md)
+
 自动注册默认使用安装目录名；入口可声明 `name` 指定简短命令名。
 重装会刷新同名绑定。JavaScript 入口必须默认导出 `register(app)`，Python 入口必须导出 `register(app)` 函数；完整协议见
 [插件运行时合同](../../docs/plugin-runtime.md)。

package/dist/cli.d.ts

@@ -16,7 +16,7 @@ interface ParsedArgs {
     operation?: MearlLifecycleOperation | 'extension' | 'plugin' | 'provider' | 'preset' | 'profile';
     profileSource?: string;
     profileBrowser?: string;
-    presetCommand?: 'apply' | 'update' | 'status' | 'repair';
+    presetCommand?: Exclude<Parameters<typeof runPresetCommand>[0], 'repair'>;
     presetSource?: string;
     presetReplaceSkills?: string[];
     pluginName?: string;

package/dist/cli.js

@@ -2,8 +2,8 @@
 import { Command, CommanderError } from 'commander';
 import { invoke, listLiveBrowsers } from '@mearl/client/local';
 import { parseProfileSource } from '@mearl/preset/bundles';
-import { downloadMearlBrowserExtension, installMearlBrowserExtension, isUnsupportedCdpMethodError } from './browserExtension.js';
-import { runMearlLifecycle } from './lifecycle.js';
+import { downloadMearlBrowserExtension, installMearlBrowserExtension, isUnsupportedCdpMethodError, } from './browserExtension.js';
+import { runMearlLifecycle, } from './lifecycle.js';
 import { isMearlReleaseLine } from './version.js';
 import { ensureOfficialPlugin, installPlugins, setupPlugin, uninstallPlugin } from './plugin.js';
 import { installProviderPackage, uninstallProviderPackage, updateProviderPackage, } from './provider.js';
@@ -30,18 +30,28 @@ export function parseSetupArgs(argv) {
     if (argv[0] === 'profile') {
         if (argv.length === 2 && (argv[1] === '--help' || argv[1] === '-h'))
             return { ...baseParsedArgs(), help: true };
-        if (argv[1] !== 'install' || !argv[2] || (argv.length !== 3 && !(argv.length === 5 && argv[3] === '--browser' && argv[4]))) {
+        if (argv[1] !== 'install' ||
+            !argv[2] ||
+            (argv.length !== 3 && !(argv.length === 5 && argv[3] === '--browser' && argv[4]))) {
             throw new Error('profile requires install <GitHub owner/repo[@ref] or HTTPS bundle URL> [--browser <id-or-name>]');
         }
         parseProfileSource(argv[2]);
-        return { ...baseParsedArgs(), operation: 'profile', profileSource: argv[2], profileBrowser: argv[4] };
+        return {
+            ...baseParsedArgs(),
+            operation: 'profile',
+            profileSource: argv[2],
+            profileBrowser: argv[4],
+        };
     }
     if (argv[0] === 'preset') {
-        if (argv[1] === 'repair') {
-            const command = new Command('preset repair')
+        if (argv.length === 2 && (argv[1] === '--help' || argv[1] === '-h'))
+            return { ...baseParsedArgs(), help: true };
+        if (argv[1] === 'apply') {
+            const command = new Command('preset apply')
                 .exitOverride()
                 .configureOutput({ writeErr: () => { }, writeOut: () => { } })
                 .allowExcessArguments(false)
+                .argument('[source]')
                 .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' });
@@ -55,15 +65,27 @@ export function parseSetupArgs(argv) {
                 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)))
+            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 } : {}) };
+            const source = command.args[0];
+            if (source !== undefined && !source.trim())
+                throw new Error('Expected a preset source URL or path');
+            if (source !== undefined && names.length)
+                throw new Error('--replace-skill requires preset apply without a source');
+            return {
+                ...baseParsedArgs(),
+                operation: 'preset',
+                presetCommand: 'apply',
+                presetSource: source,
+                ...(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)
+        if ((argv[1] === 'update' || argv[1] === 'status' || argv[1] === 'uninstall') &&
+            argv.length === 2)
             return { ...baseParsedArgs(), operation: 'preset', presetCommand: argv[1] };
-        throw new Error('preset requires apply <source-url-or-path>, update, repair [--replace-skill <name>], or status');
+        throw new Error('preset requires apply [source-url-or-path], update, status, or uninstall');
     }
     if (argv[0] === 'provider') {
         const command = argv[1];
@@ -223,10 +245,10 @@ Environment commands:
 
 Integration commands:
   profile install <source>       Install one App profile bundle in a connected extension
-  preset apply <source>          Apply a preset, synchronize hosts and install declared components
+  preset apply [source]          Apply a URL or local file, or retry the saved snapshot
   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)
+  preset uninstall               Remove the preset from the local host and connected extensions
   plugin install <arguments...>   Install Skills and register their CLI plugins
   plugin uninstall <name>        Uninstall one CLI plugin
   plugin [name] <path>            Register an existing plugin; name overrides metadata
@@ -254,7 +276,7 @@ Extension options:
   --full                          Install the extension and complete local environment
   --force                         Replace an extension managed by another source
 
-Preset repair options:
+Preset apply options (without a source):
   --replace-skill <name>           Replace one Skill source or conflicting registration; repeat for more
 
 General options:
@@ -271,13 +293,19 @@ Examples:
   npx @mearl/setup uninstall --full
   npx @mearl/setup plugin uninstall tabs
   npx @mearl/setup provider install @example/mearl-provider-device
-  npx @mearl/setup preset repair --replace-skill example-skill
+  npx @mearl/setup preset apply --replace-skill example-skill
   npx @mearl/setup extension --full`;
     console.log(output.replaceAll('npx @mearl/setup', SETUP_COMMAND));
 }
 async function runSetupLifecycle(options, dependencies) {
     let preset;
-    const callback = options.operation === 'uninstall' ? undefined : { onPresetStatus: (status) => { preset = status; } };
+    const callback = options.operation === 'uninstall'
+        ? undefined
+        : {
+            onPresetStatus: (status) => {
+                preset = status;
+            },
+        };
     const lifecycle = dependencies.runLifecycle ?? runMearlLifecycle;
     const defaultPresetSource = process.env.MEARL_SETUP_DEFAULT_PRESET;
     const configured = defaultPresetSource ? { ...options, defaultPresetSource } : options;
@@ -298,7 +326,8 @@ async function runSetupLifecycle(options, dependencies) {
 }
 async function installProfile(source, browser) {
     if (!browser) {
-        const extensions = listLiveBrowsers().filter(target => target.transport === 'extension' && (target.status === undefined || target.status === 'connected'));
+        const extensions = listLiveBrowsers().filter(target => target.transport === 'extension' &&
+            (target.status === undefined || target.status === 'connected'));
         if (extensions.length !== 1)
             throw new Error(extensions.length
                 ? 'Multiple extensions are connected. Select one with --browser <id-or-name>.'
@@ -341,7 +370,9 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
         try {
             const run = dependencies.runPreset ?? runPresetCommand;
             const result = parsed.presetReplaceSkills
-                ? await run(parsed.presetCommand, parsed.presetSource, { replaceSkills: 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/preset.d.ts

@@ -93,16 +93,21 @@ export declare class PresetInstaller {
     private stageSource;
     /** Save exact resources and desired selection; activate once after runtime setup, then retry via resume. */
     stage(source: string, options?: PresetApplyOptions): Promise<StagedPresetInstallation>;
-    apply(source: string, options?: PresetApplyOptions): Promise<PresetInstallStatus>;
+    apply(source?: string, options?: PresetApplyOptions & {
+        replaceSkills?: readonly string[];
+    }): Promise<PresetInstallStatus>;
     update(options?: Pick<PresetApplyOptions, 'validatePrepared' | 'skipUnchanged' | 'signal'>): Promise<PresetInstallStatus>;
     resume(expectedRevision: string, options?: {
         replaceSkills?: readonly string[];
     }): Promise<PresetInstallStatus>;
+    private resumeSelected;
+    /** @deprecated Use apply() without a source. */
     repair(options?: {
         replaceSkills?: readonly string[];
     }): Promise<PresetInstallStatus>;
+    uninstall(): Promise<PresetInstallStatus>;
     configure(value: JsonObject): Promise<PresetInstallStatus>;
 }
-export declare function runPresetCommand(command: 'apply' | 'update' | 'status' | 'repair', source?: string, options?: {
+export declare function runPresetCommand(command: 'apply' | 'update' | 'status' | 'uninstall' | 'repair', source?: string, options?: {
     replaceSkills?: readonly string[];
 }): Promise<PresetInstallStatus>;

package/dist/preset.js

@@ -4,15 +4,24 @@ import { createRequire } from 'node:module';
 import { resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { invoke, invokeLocalHost, listLiveBrowsers, SOCKET_PATH } from '@mearl/client/local';
+import { uninstallOfficialPluginCatalog } from '@mearl/client/plugin';
 import { mergePresetDefaults } from '@mearl/preset';
-import { BundleError, createBundleFetchLoader, preparePreset } from '@mearl/preset/bundles';
+import { BundleError, createBundleFetchLoader, preparePreset, } from '@mearl/preset/bundles';
 import { PresetInstallationStore, presetSelectionRevision } from './presetStore.js';
+import { claimPresetInstallation } from './presetInstallationLease.js';
 const installationSite = createRequire(import.meta.url)('@mearl/preset/installation-site.json');
-export const MEARL_INSTALLATION_CONFIG_URL = new URL('installation.json', installationSite.url).href;
+export const MEARL_INSTALLATION_CONFIG_URL = new URL('installation.json', installationSite.url)
+    .href;
 /** Runtime overrides apply to this local process, never to browser-supplied install requests. */
 export function resolveInstallationConfigUrl(value = process.env.MEARL_INSTALLATION_CONFIG_URL, allowLoopback = false) {
     const url = new URL(value || MEARL_INSTALLATION_CONFIG_URL);
-    if (url.username || url.password || url.hash || (url.protocol !== 'https:' && !(allowLoopback && url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname))))
+    if (url.username ||
+        url.password ||
+        url.hash ||
+        (url.protocol !== 'https:' &&
+            !(allowLoopback &&
+                url.protocol === 'http:' &&
+                ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname))))
         throw new Error('Invalid installation configuration URL');
     return url;
 }
@@ -52,7 +61,8 @@ export function createNodePresetLoader() {
                 await handle.close();
             }
         }
-        if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) {
+        if (url.protocol !== 'https:' &&
+            !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) {
             throw new BundleError('BUNDLE_INVALID', 'Preset sources require HTTPS, local files or loopback HTTP');
         }
         return network(source, options);
@@ -68,12 +78,20 @@ function sourceUrl(source) {
 }
 function localHosts(allowStart = false) {
     const configured = process.env.MEARL_SOCKET_PATH?.trim();
-    const hosts = configured ? [{ id: 'local', socketPath: configured }] : listLiveBrowsers().filter(browser => !browser.provider).map(browser => ({ id: browser.browserId, socketPath: browser.socketPath }));
-    return hosts.length ? Array.from(new Map(hosts.map(host => [host.socketPath, host])).values()) : [{ id: 'local', ...(allowStart ? {} : { socketPath: SOCKET_PATH }) }];
+    const hosts = configured
+        ? [{ id: 'local', socketPath: configured }]
+        : listLiveBrowsers()
+            .filter(browser => !browser.provider)
+            .map(browser => ({ id: browser.browserId, socketPath: browser.socketPath }));
+    return hosts.length
+        ? Array.from(new Map(hosts.map(host => [host.socketPath, host])).values())
+        : [{ id: 'local', ...(allowStart ? {} : { socketPath: SOCKET_PATH }) }];
 }
 export function connectedPresetExtensions(browsers, socketPath) {
-    return browsers.filter(browser => !browser.provider && browser.transport === 'extension' &&
-        (browser.status === undefined || browser.status === 'connected') && (!socketPath || browser.socketPath === socketPath));
+    return browsers.filter(browser => !browser.provider &&
+        browser.transport === 'extension' &&
+        (browser.status === undefined || browser.status === 'connected') &&
+        (!socketPath || browser.socketPath === socketPath));
 }
 /** Installation and live acknowledgements are distinct; browser/external installs remain pending. */
 export class PresetInstaller {
@@ -86,16 +104,30 @@ export class PresetInstaller {
     invokeHost(action, data, target, timeoutSec, allowStart = false) {
         if (!this.options.invoke && !target.socketPath && !allowStart)
             return Promise.reject(new Error('HOST_UNAVAILABLE'));
-        return (this.options.invoke ?? (target.socketPath ? invoke : invokeLocalHost))(action, data, { socketPath: target.socketPath, timeoutSec });
+        return (this.options.invoke ?? (target.socketPath ? invoke : invokeLocalHost))(action, data, {
+            socketPath: target.socketPath,
+            timeoutSec,
+        });
     }
-    async hostStatus(reload, nodeRevision, installationRevision) {
-        const targets = this.options.hosts?.() ?? localHosts(reload);
+    async hostStatus(reload, nodeRevision, installationRevision, targets = this.options.hosts?.() ?? localHosts(reload)) {
         return Promise.all(targets.map(async (target) => {
             try {
                 const result = await this.invokeHost(reload ? 'node_capabilities_reload' : 'node_capabilities_status', reload ? { structured: true } : {}, target, 15, reload);
                 if (reload && result?.accepted === false)
-                    return { id: target.id, state: 'rejected', error: typeof result.error === 'string' ? result.error : 'Node capability activation was rejected' };
-                return { id: target.id, state: result?.revision === nodeRevision && result?.installationRevision === installationRevision ? 'active' : 'pending' };
+                    return {
+                        id: target.id,
+                        state: 'rejected',
+                        error: typeof result.error === 'string'
+                            ? result.error
+                            : 'Node capability activation was rejected',
+                    };
+                return {
+                    id: target.id,
+                    state: result?.revision === nodeRevision &&
+                        result?.installationRevision === installationRevision
+                        ? 'active'
+                        : 'pending',
+                };
             }
             catch {
                 return { id: target.id, state: 'pending', error: 'HOST_UNAVAILABLE' };
@@ -105,19 +137,42 @@ export class PresetInstaller {
     async browserStatus(reload, browserRevision, installationRevision) {
         const targets = this.options.connectedExtensionsOnly
             ? connectedPresetExtensions(listLiveBrowsers(), process.env.MEARL_SOCKET_PATH?.trim()).map(browser => ({ id: browser.browserId, socketPath: browser.socketPath }))
-            : this.options.hosts?.() ?? localHosts(reload);
+            : (this.options.hosts?.() ?? localHosts(reload));
         return Promise.all(targets.map(async (target) => {
             try {
                 const result = await this.invokeHost(reload ? 'preset_browser_sync' : 'preset_browser_status', reload ? { installationRevision } : {}, target, reload ? 130 : 15, reload);
                 if (result?.accepted === false)
-                    return { id: target.id, state: 'rejected', settingsReady: false, error: typeof result.error === 'string' ? result.error : 'Browser preset activation rejected' };
+                    return {
+                        id: target.id,
+                        state: 'rejected',
+                        settingsReady: false,
+                        error: typeof result.error === 'string'
+                            ? result.error
+                            : 'Browser preset activation rejected',
+                    };
                 const error = Array.isArray(result?.permissionPending) && result.permissionPending.length
                     ? 'PRESET_DOMAIN_PERMISSION_REQUIRED: Open extension settings and authorize preset domains'
-                    : typeof result?.error === 'string' ? result.error : undefined;
-                return { id: target.id, state: result?.ready === true && result?.browserRevision === browserRevision && result?.installationRevision === installationRevision ? 'active' : 'pending', settingsReady: result?.settingsReady === true, ...(error ? { error } : {}) };
+                    : typeof result?.error === 'string'
+                        ? result.error
+                        : undefined;
+                return {
+                    id: target.id,
+                    state: result?.ready === true &&
+                        result?.browserRevision === browserRevision &&
+                        result?.installationRevision === installationRevision
+                        ? 'active'
+                        : 'pending',
+                    settingsReady: result?.settingsReady === true,
+                    ...(error ? { error } : {}),
+                };
             }
             catch {
-                return { id: target.id, state: 'pending', settingsReady: false, error: 'BROWSER_UNAVAILABLE' };
+                return {
+                    id: target.id,
+                    state: 'pending',
+                    settingsReady: false,
+                    error: 'BROWSER_UNAVAILABLE',
+                };
             }
         }));
     }
@@ -126,14 +181,23 @@ export class PresetInstaller {
         if (!target)
             return {};
         try {
-            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))
+            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')
                 throw new Error('Invalid plugin catalog readiness');
             const seen = new Set();
             for (const entry of result.components) {
-                if (!entry || !['skills', 'providers'].includes(entry.kind) || typeof entry.id !== 'string' || !['ready', 'pending', 'conflict'].includes(entry.state) || (entry.reason !== undefined && typeof entry.reason !== 'string'))
+                if (!entry ||
+                    !['skills', 'providers'].includes(entry.kind) ||
+                    typeof entry.id !== 'string' ||
+                    !['ready', 'pending', 'conflict'].includes(entry.state) ||
+                    (entry.reason !== undefined && typeof entry.reason !== 'string'))
                     throw new Error('Invalid component installation status');
                 const key = `${entry.kind}:${entry.id}`;
                 if (seen.has(key))
@@ -148,7 +212,14 @@ export class PresetInstaller {
     }
     async status() {
         const current = await this.store.current();
-        const result = { revision: presetSelectionRevision(current), ready: false, hosts: [], browsers: [], pending: [], warnings: [] };
+        const result = {
+            revision: presetSelectionRevision(current),
+            ready: false,
+            hosts: [],
+            browsers: [],
+            pending: [],
+            warnings: [],
+        };
         if (!current.receipt || !current.prepared)
             return result;
         const { preset } = current.prepared;
@@ -161,8 +232,9 @@ export class PresetInstaller {
         result.browserRevision = receipt.browserRevision;
         const browserSyncRequired = receipt.browserSyncRequired === true && !this.options.connectedExtensionsOnly;
         result.browserSyncRequired = browserSyncRequired;
-        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.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');
         if (receipt.browserSyncRequired)
@@ -176,7 +248,9 @@ export class PresetInstaller {
                     if (browserSyncRequired && !browserReady)
                         result.pending.push({ kind: 'packages', id, runtime, reason: 'BROWSER_SYNC_REQUIRED' });
                 }
-                else if (!receipt.managedModules.includes(id) && Object.keys(current.prepared.bundles.find(bundle => bundle.manifest.id === id)?.manifest.contributions?.nodeRuntimes ?? {}).length)
+                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' });
@@ -186,7 +260,12 @@ export class PresetInstaller {
         const hasCatalog = Boolean(current.activation?.bindings['plugins.catalog']);
         const components = hasExternal || hasCatalog ? await this.componentStatus(false, receipt) : {};
         if (hasCatalog && components.status?.catalogReady !== true)
-            result.pending.push({ kind: 'preset', id: preset.id, runtime: 'node', reason: 'PLUGIN_CATALOG_SYNC_REQUIRED' });
+            result.pending.push({
+                kind: 'preset',
+                id: preset.id,
+                runtime: 'node',
+                reason: 'PLUGIN_CATALOG_SYNC_REQUIRED',
+            });
         if (components.error)
             result.warnings.push(`Component readiness check failed: ${components.error}`);
         for (const kind of ['skills', 'providers'])
@@ -195,14 +274,41 @@ export class PresetInstaller {
                     continue;
                 const actual = components.status?.components.find(component => component.kind === kind && component.id === id);
                 if (actual?.state !== 'ready')
-                    result.pending.push({ kind, id, runtime: 'node', reason: actual?.reason ?? 'INSTALL_REQUIRED' });
+                    result.pending.push({
+                        kind,
+                        id,
+                        runtime: 'node',
+                        reason: actual?.reason ?? 'INSTALL_REQUIRED',
+                    });
             }
-        if (receipt.nodeSyncRequired && !nodeReady && !result.pending.some(entry => entry.reason === 'HOST_SYNC_REQUIRED'))
-            result.pending.push({ kind: 'preset', id: preset.id, runtime: 'node', reason: 'HOST_SYNC_REQUIRED' });
-        if (browserSyncRequired && !browserReady && !result.pending.some(entry => entry.reason === 'BROWSER_SYNC_REQUIRED'))
-            result.pending.push({ kind: 'preset', id: preset.id, runtime: 'browser', reason: 'BROWSER_SYNC_REQUIRED' });
-        if (browserSyncRequired && browserReady && Object.keys(result.settings ?? {}).length && !result.browsers.every(host => host.settingsReady))
-            result.pending.push({ kind: 'preset', id: preset.id, runtime: 'browser', reason: 'SETTINGS_APPLY_REQUIRED' });
+        if (receipt.nodeSyncRequired &&
+            !nodeReady &&
+            !result.pending.some(entry => entry.reason === 'HOST_SYNC_REQUIRED'))
+            result.pending.push({
+                kind: 'preset',
+                id: preset.id,
+                runtime: 'node',
+                reason: 'HOST_SYNC_REQUIRED',
+            });
+        if (browserSyncRequired &&
+            !browserReady &&
+            !result.pending.some(entry => entry.reason === 'BROWSER_SYNC_REQUIRED'))
+            result.pending.push({
+                kind: 'preset',
+                id: preset.id,
+                runtime: 'browser',
+                reason: 'BROWSER_SYNC_REQUIRED',
+            });
+        if (browserSyncRequired &&
+            browserReady &&
+            Object.keys(result.settings ?? {}).length &&
+            !result.browsers.every(host => host.settingsReady))
+            result.pending.push({
+                kind: 'preset',
+                id: preset.id,
+                runtime: 'browser',
+                reason: 'SETTINGS_APPLY_REQUIRED',
+            });
         result.ready = result.pending.length === 0;
         return result;
     }
@@ -217,15 +323,22 @@ export class PresetInstaller {
             await this.hostStatus(true, previous.activation?.revision ?? '', previous.activation?.installationRevision ?? '');
             throw new Error(`Node activation rejected; previous selection restored: ${rejection.error}`);
         }
-        const browsers = receipt.browserSyncRequired ? await this.browserStatus(true, receipt.browserRevision, receipt.revision) : [];
+        const browsers = receipt.browserSyncRequired
+            ? await this.browserStatus(true, receipt.browserRevision, receipt.revision)
+            : [];
         const rejected = browsers.find(host => host.state === 'rejected');
         if (rejected && !this.options.connectedExtensionsOnly)
             throw new Error(`Browser activation rejected; installed selection retained for retry: ${rejected.error}`);
         const installed = await this.store.current({ verifyResources: false });
         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, replaceSkills) : {};
+        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, replaceSkills)
+            : {};
         const status = await this.status();
         if (rejected)
             status.warnings.push(`Browser preset activation rejected by ${rejected.id}: ${rejected.error}`);
@@ -242,7 +355,11 @@ export class PresetInstaller {
         return status;
     }
     async stageSource(source, expectedRevision, options) {
-        const prepared = await preparePreset(sourceUrl(source), { mearlApiVersion: this.store.mearlApiVersion, load: this.options.load ?? createNodePresetLoader(), signal: options.signal });
+        const prepared = await preparePreset(sourceUrl(source), {
+            mearlApiVersion: this.store.mearlApiVersion,
+            load: this.options.load ?? createNodePresetLoader(),
+            signal: options.signal,
+        });
         if (options.expectedId !== undefined && prepared.preset.id !== options.expectedId)
             throw new BundleError('BUNDLE_INVALID', 'The preset identity differs from the accepted installation');
         await options.validatePrepared?.(prepared);
@@ -251,17 +368,22 @@ export class PresetInstaller {
             if (presetSelectionRevision(current) !== expectedRevision)
                 throw new BundleError('BUNDLE_CONFLICT', 'The installed preset changed during update');
             if (current.receipt && current.prepared?.snapshot.revision === prepared.snapshot.revision) {
-                return { revision: current.receipt.revision, activate: async () => {
+                return {
+                    revision: current.receipt.revision,
+                    activate: async () => {
                         const status = await this.status();
                         if (status.revision !== expectedRevision)
                             throw new BundleError('BUNDLE_CONFLICT', 'The installed preset changed during update');
                         return status.ready ? status : this.resume(current.receipt.revision);
-                    } };
+                    },
+                };
             }
         }
         const receipt = await this.store.apply(prepared, { ...options, expectedRevision });
         let activated = false;
-        return { revision: receipt.revision, activate: async () => {
+        return {
+            revision: receipt.revision,
+            activate: async () => {
                 if (activated)
                     throw new Error('Staged installation was already activated; use resume with its revision to retry');
                 activated = true;
@@ -269,11 +391,17 @@ export class PresetInstaller {
                 if (current.receipt?.revision !== receipt.revision)
                     throw new BundleError('BUNDLE_CONFLICT', 'The selected preset changed before runtime setup completed');
                 return this.synchronize(current.receipt, expectedRevision);
-            } };
+            },
+        };
     }
     /** 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) }) };
+        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)
@@ -281,42 +409,161 @@ export class PresetInstaller {
         return this.stageSource(source, revision, accepted);
     }
     async apply(source, options = {}) {
+        if (source === undefined)
+            return this.resumeSelected(options);
+        if (options.replaceSkills !== undefined)
+            throw new Error('Skill replacements require preset apply without a source');
         return (await this.stage(source, options)).activate();
     }
     async update(options = {}) {
         const current = await this.store.current({ verifyResources: false });
         if (!current.receipt)
             throw new Error('No preset is installed');
-        return this.apply(current.receipt.snapshot.source, { ...options, expectedRevision: presetSelectionRevision(current) });
+        return this.apply(current.receipt.snapshot.source, {
+            ...options,
+            expectedRevision: presetSelectionRevision(current),
+        });
     }
     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');
         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)))
+        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 = {}) {
+    async resumeSelected(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);
     }
+    /** @deprecated Use apply() without a source. */
+    async repair(options = {}) {
+        return this.resumeSelected(options);
+    }
+    async uninstall() {
+        const current = await this.store.current({ verifyResources: false });
+        const { receipt, preset } = current;
+        const configured = process.env.MEARL_SOCKET_PATH?.trim();
+        const live = this.options.hosts
+            ? []
+            : listLiveBrowsers().filter(browser => !browser.provider && (!configured || browser.socketPath === configured));
+        const explicitHosts = this.options
+            .hosts?.()
+            .filter(target => !configured || target.socketPath === configured);
+        const browserTargets = explicitHosts ??
+            connectedPresetExtensions(live).map(browser => ({
+                id: browser.browserId,
+                socketPath: browser.socketPath,
+            }));
+        if (configured && !browserTargets.length)
+            throw new Error('MEARL_SOCKET_PATH does not identify a connected extension.');
+        const selections = (await Promise.all(browserTargets.map(async (target) => {
+            const status = await this.invokeHost('preset_browser_status', {}, target, 15);
+            if (status?.browserRevision === null && !status.error)
+                return;
+            if (typeof status?.browserRevision !== 'string')
+                throw new Error(`Cannot read the preset in ${target.id}. Reconnect the extension and retry.`);
+            if (receipt &&
+                status.installationRevision !== receipt.revision &&
+                (status.presetId !== preset?.id || status.presetSource !== receipt.snapshot.source))
+                return;
+            if (!receipt && !configured)
+                throw new Error('Set MEARL_SOCKET_PATH to remove a browser preset without a local selection.');
+            if (status.uninstallSupported !== true || status.installationToken === undefined) {
+                throw new Error(`Update the Native Host and extension for ${target.id} before removing its preset.`);
+            }
+            return { target, status };
+        }))).filter(selection => selection !== undefined);
+        const result = {
+            revision: null,
+            ready: true,
+            hosts: [],
+            browsers: [],
+            pending: [],
+            warnings: [],
+        };
+        let remaining = current.activation;
+        if (receipt) {
+            const lease = claimPresetInstallation();
+            try {
+                remaining = await this.store.uninstall(receipt.revision, uninstallOfficialPluginCatalog);
+            }
+            finally {
+                lease.release();
+            }
+            try {
+                await this.store.collectGarbage();
+            }
+            catch (error) {
+                result.warnings.push(`Preset resource cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        const hosts = explicitHosts ?? [
+            ...new Map(live.map(browser => [
+                browser.socketPath,
+                { id: browser.browserId, socketPath: browser.socketPath },
+            ])).values(),
+        ];
+        result.hosts = await this.hostStatus(true, remaining?.revision ?? null, null, hosts);
+        result.browsers = await Promise.all(selections.map(async ({ target, status }) => {
+            try {
+                const removed = await this.invokeHost('preset_browser_uninstall', {
+                    browserRevision: status.browserRevision,
+                    installationToken: status.installationToken,
+                }, target, 130);
+                if (removed?.accepted !== true || removed.browserRevision !== null)
+                    throw new Error(removed?.error ?? 'Browser preset removal was not acknowledged');
+                return { id: target.id, state: 'active', settingsReady: false };
+            }
+            catch (error) {
+                return {
+                    id: target.id,
+                    state: 'pending',
+                    settingsReady: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        }));
+        result.ready = [...result.hosts, ...result.browsers].every(host => host.state === 'active');
+        return result;
+    }
     async configure(value) {
         const current = await this.store.current();
         if (!current.prepared)
             throw new Error('No preset is installed');
-        const receipt = await this.store.apply(current.prepared, { expectedRevision: presetSelectionRevision(current), overrides: value });
+        const receipt = await this.store.apply(current.prepared, {
+            expectedRevision: presetSelectionRevision(current),
+            overrides: value,
+        });
         return this.synchronize(receipt, presetSelectionRevision(current));
     }
 }
 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({ connectedExtensionsOnly: true });
     if (command === 'repair')
         return installer.repair(options);
-    return command === 'status' ? installer.status() : command === 'update' ? installer.update() : installer.apply(source);
+    if ((command !== 'apply' || source !== undefined) && options.replaceSkills !== undefined)
+        throw new Error('Skill replacements require preset apply without a source');
+    switch (command) {
+        case 'apply':
+            return installer.apply(source, options);
+        case 'update':
+            return installer.update();
+        case 'status':
+            return installer.status();
+        case 'uninstall':
+            return installer.uninstall();
+    }
 }

package/dist/skillSourceReceipts.d.ts

@@ -22,4 +22,4 @@ export declare function gitSource(source: 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;
+export declare function matchesTrackedSkillSource(requested: string, tracked: TrackedSkillSource, normalize?: (source: string, sourceType?: string) => string, refMatch?: 'exact' | 'missing'): boolean;

package/dist/skillSourceReceipts.js

@@ -4,7 +4,11 @@ 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');
+    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);
@@ -33,12 +37,28 @@ export function readTrackedSkillSources(scope, cwd, options = {}) {
         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' }];
+        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);
+    return (source.sourceType === undefined ||
+        ['github', 'gitlab', 'git', 'local', 'well-known'].includes(source.sourceType));
 }
 export function gitSource(source, ref) {
     if (/^[\w.-]+\/[\w.-]+$/.test(source))
@@ -46,17 +66,31 @@ export function gitSource(source, 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)
+    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: `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) {
+export function matchesTrackedSkillSource(requested, tracked, normalize = source => source, refMatch = 'exact') {
     const location = (source, ref, sourceType) => {
         const value = normalize(source, sourceType);
         if (typeof value !== 'string' || !value || value.length > 8192 || /[\0\r\n]/.test(value))
@@ -64,7 +98,9 @@ export function matchesTrackedSkillSource(requested, tracked, normalize = 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);
+        const parsed = isAbsolute(plain)
+            ? { repository: plain, ref: ref ?? fragment }
+            : gitSource(plain, ref ?? fragment);
         let repository = parsed.repository;
         if (repository.startsWith('file:'))
             repository = fileURLToPath(repository);
@@ -81,14 +117,22 @@ export function matchesTrackedSkillSource(requested, tracked, normalize = source
     try {
         const expected = location(requested);
         const actual = location(tracked.source, tracked.ref, tracked.sourceType);
-        if (expected.repository !== actual.repository || expected.ref !== actual.ref)
+        if (expected.repository !== actual.repository)
+            return false;
+        if (refMatch === 'missing'
+            ? !expected.ref || actual.ref !== undefined
+            : expected.ref !== actual.ref)
             return false;
         if (!expected.subdirectory)
             return true;
-        const path = (tracked.skillPath ?? actual.subdirectory ?? '').replace(/(?:^|\/)SKILL\.md$/, '').replace(/\/+$/, '');
+        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;
+        return (refMatch === 'exact' &&
+            normalize(requested) === normalize(tracked.source, tracked.sourceType) &&
+            !tracked.ref);
     }
 }

package/dist/skillSources.d.ts

@@ -1,6 +1,6 @@
 import { type CommandRunner } from '@mearl/daemon-core';
 import { readTrackedSkillSources, type SourceOptions, type SkillSourceScope, type TrackedSkillSource } from './skillSourceReceipts.js';
-export { isPublicSkillSource, matchesTrackedSkillSource, readTrackedSkillSources } 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>;

package/dist/skillSources.js

@@ -6,12 +6,15 @@ import { homedir, tmpdir } from 'node:os';
 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, getSkillEnabled, 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';
-import { gitSource, isPublicSkillSource, matchesTrackedSkillSource, readTrackedSkillSources } from './skillSourceReceipts.js';
-export { isPublicSkillSource, matchesTrackedSkillSource, readTrackedSkillSources } from './skillSourceReceipts.js';
+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();
+    return text
+        .match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1]
+        .match(/^name:\s*["']?([^"'\r\n]+?)["']?\s*$/m)?.[1]
+        ?.trim();
 }
 async function findSkillDirectory(root, name, skillPath) {
     if (skillPath) {
@@ -47,7 +50,8 @@ export async function hashSkillDirectory(directory, ignoreRuntimeFiles = false)
     let total = 0;
     const visit = async (current) => {
         for (const entry of await readdir(current, { withFileTypes: true })) {
-            if (['.git', 'node_modules'].includes(entry.name) || (ignoreRuntimeFiles && ['__pycache__', '.DS_Store'].includes(entry.name)))
+            if (['.git', 'node_modules'].includes(entry.name) ||
+                (ignoreRuntimeFiles && ['__pycache__', '.DS_Store'].includes(entry.name)))
                 continue;
             const file = join(current, entry.name);
             if (entry.isDirectory())
@@ -57,7 +61,13 @@ export async function hashSkillDirectory(directory, ignoreRuntimeFiles = false)
                 total += info.size;
                 if (total > 64 * 1024 * 1024 || files.length >= 10_000)
                     throw new Error('Skill source exceeds the comparison limit');
-                files.push({ path: relative(directory, file).split(sep).join('/').replace(ignoreRuntimeFiles ? /^SKILL\.md\.mearl-disabled$/ : /$^/, 'SKILL.md'), bytes: await readFile(file) });
+                files.push({
+                    path: relative(directory, file)
+                        .split(sep)
+                        .join('/')
+                        .replace(ignoreRuntimeFiles ? /^SKILL\.md\.mearl-disabled$/ : /$^/, 'SKILL.md'),
+                    bytes: await readFile(file),
+                });
             }
         }
     };
@@ -71,7 +81,10 @@ export async function hashSkillDirectory(directory, ignoreRuntimeFiles = false)
 }
 /** Checks source content in a temporary checkout; never invokes the mutating Skills `check` alias. */
 export async function checkTrackedSkillUpdates(options = {}) {
-    const sources = [...readTrackedSkillSources('global', undefined, options), ...(options.cwd ? readTrackedSkillSources('project', options.cwd, options) : [])];
+    const sources = [
+        ...readTrackedSkillSources('global', undefined, options),
+        ...(options.cwd ? readTrackedSkillSources('project', options.cwd, options) : []),
+    ];
     if (sources.some(source => !isPublicSkillSource(source)))
         throw new Error('Installed Skills require an external manager. Enable its preset.');
     if (sources.length > 500)
@@ -88,12 +101,27 @@ export async function checkTrackedSkillUpdates(options = {}) {
             let checkout = checkouts.get(key);
             if (!checkout) {
                 const target = join(temporary, String(checkouts.size));
-                checkout = local ? Promise.resolve(local) : (async () => {
-                    const result = await runner('git', ['clone', '--depth', '1', '--filter=blob:none', ...(location.ref ? ['--branch', location.ref] : []), '--', location.repository, target], { capture: true, env: { ...(options.env ?? process.env), GIT_TERMINAL_PROMPT: '0' }, timeoutMs: 120_000 });
-                    if (result.code !== 0)
-                        throw new Error(`Unable to inspect Skill source: ${source.name}`);
-                    return target;
-                })();
+                checkout = local
+                    ? Promise.resolve(local)
+                    : (async () => {
+                        const result = await runner('git', [
+                            'clone',
+                            '--depth',
+                            '1',
+                            '--filter=blob:none',
+                            ...(location.ref ? ['--branch', location.ref] : []),
+                            '--',
+                            location.repository,
+                            target,
+                        ], {
+                            capture: true,
+                            env: { ...(options.env ?? process.env), GIT_TERMINAL_PROMPT: '0' },
+                            timeoutMs: 120_000,
+                        });
+                        if (result.code !== 0)
+                            throw new Error(`Unable to inspect Skill source: ${source.name}`);
+                        return target;
+                    })();
                 checkouts.set(key, checkout);
             }
             const root = await realpath(await checkout);
@@ -107,10 +135,12 @@ export async function checkTrackedSkillUpdates(options = {}) {
                 changed = result.stdout.trim() !== source.expectedHash;
             }
             else if (source.expectedHash && source.hashKind === 'folder')
-                changed = await hashSkillDirectory(directory) !== source.expectedHash;
+                changed = (await hashSkillDirectory(directory)) !== source.expectedHash;
             else {
-                const installed = join(source.scope === 'global' ? options.homeDirectory ?? homedir() : options.cwd, '.agents', 'skills', source.name);
-                changed = await hashSkillDirectory(directory, true) !== await hashSkillDirectory(installed, true);
+                const installed = join(source.scope === 'global' ? (options.homeDirectory ?? homedir()) : options.cwd, '.agents', 'skills', source.name);
+                changed =
+                    (await hashSkillDirectory(directory, true)) !==
+                        (await hashSkillDirectory(installed, true));
             }
             if (changed)
                 updates.push({ name: source.name, source: source.source, scope: source.scope });
@@ -128,7 +158,10 @@ export function readLinkedSkillSource(directory, name) {
             return undefined;
         const actual = realpathSync(directory);
         const git = (...args) => execFileSync('git', ['--no-optional-locks', '-c', 'core.fsmonitor=false', '-C', actual, ...args], {
-            encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2_000, maxBuffer: 16_384,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 2_000,
+            maxBuffer: 16_384,
         }).trim();
         const root = git('rev-parse', '--show-toplevel');
         const folder = relative(root, actual);
@@ -169,29 +202,44 @@ function canonicalPath(path) {
         return parent === absolute ? absolute : join(canonicalPath(parent), basename(absolute));
     }
 }
-function hasOnlySetupRegistrations(directory) {
+function hasOnlySetupRegistrations(directory, allowUnregistered = false) {
     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);
+    const registrations = listPluginNames()
+        .flatMap(name => findPluginRegistration(name) ?? [])
+        .filter(registration => contains(resolve(directory), resolve(registration.entry)) ||
+        contains(canonicalPath(directory), canonicalPath(registration.entry)));
+    return ((allowUnregistered || 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))
         throw new Error('Invalid Skill identity');
     const directory = join(options.homeDirectory ?? homedir(), '.agents', 'skills', name);
-    if (existsSync(join(directory, 'SKILL.md')) && existsSync(join(directory, DISABLED_SKILL_MANIFEST)))
+    if (existsSync(join(directory, 'SKILL.md')) &&
+        existsSync(join(directory, DISABLED_SKILL_MANIFEST)))
         return { state: 'conflict', reason: 'SKILL_MANIFEST_CONFLICT' };
-    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))) {
+    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))) {
         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' };
+        if (receipt &&
+            (options.externalManager || isPublicSkillSource(receipt)) &&
+            metadata?.name === name) {
+            // A missing ref requires installing the requested ref before the Skill can be ready.
+            const missingRef = matchesTrackedSkillSource(source, receipt, options.normalizeSource, 'missing');
+            const declaredMigration = options.migrateFrom?.some(previous => matchesTrackedSkillSource(previous, receipt, options.normalizeSource));
+            if ((missingRef || declaredMigration) && hasOnlySetupRegistrations(directory, missingRef)) {
+                return { state: 'migration', reason: 'SKILL_SOURCE_MIGRATION_REQUIRED' };
+            }
         }
         return { state: 'conflict', reason: 'SKILL_SOURCE_CONFLICT' };
     }
@@ -202,7 +250,8 @@ export function inspectGlobalSkill(source, name, version, options = {}) {
         return { state: 'conflict', reason: 'SKILL_SOURCE_UNKNOWN' };
     if (metadata.name !== name)
         return { state: 'conflict', reason: 'SKILL_MANIFEST_IDENTITY' };
-    if (version && (!metadata.version || !valid(metadata.version) || !satisfies(metadata.version, version)))
+    if (version &&
+        (!metadata.version || !valid(metadata.version) || !satisfies(metadata.version, version)))
         return { state: 'version', reason: 'SKILL_VERSION_REQUIRED' };
     const entry = findPluginDirectoryEntry(directory);
     const names = listPluginNames().filter(name => {
@@ -212,10 +261,13 @@ export function inspectGlobalSkill(source, name, version, options = {}) {
     const managedNames = names.filter(name => findPluginRegistration(name)?.managedBy === OFFICIAL_PLUGIN_MANAGER);
     // User aliases may share a managed Skill without participating in its readiness or cleanup.
     const requiredNames = managedNames.length ? managedNames : names;
-    if (entry && (requiredNames.length !== 1 || !requiredNames.some(name => {
-        const registration = findPluginRegistration(name);
-        return resolve(registration.entry) === resolve(entry) && !pluginRegistrationNeedsRefresh(registration, true);
-    })))
+    if (entry &&
+        (requiredNames.length !== 1 ||
+            !requiredNames.some(name => {
+                const registration = findPluginRegistration(name);
+                return (resolve(registration.entry) === resolve(entry) &&
+                    !pluginRegistrationNeedsRefresh(registration, true));
+            })))
         return { state: 'registration', reason: 'SKILL_PLUGIN_REGISTRATION_REQUIRED' };
     if (!entry && names.length)
         return { state: 'registration', reason: 'SKILL_PLUGIN_REGISTRATION_REQUIRED' };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",
@@ -79,11 +79,11 @@
     "ws": "^8.18.3",
     "semver": "^7.8.5",
     "adm-zip": "^0.6.1",
-    "@mearl/client": "3.0.1",
-    "@mearl/provider": "3.0.1",
-    "@mearl/daemon-core": "3.0.1",
-    "@mearl/preset": "3.0.1",
-    "@mearl/browser-core": "3.0.1"
+    "@mearl/provider": "3.0.2",
+    "@mearl/preset": "3.0.2",
+    "@mearl/browser-core": "3.0.2",
+    "@mearl/daemon-core": "3.0.2",
+    "@mearl/client": "3.0.2"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",