@mearl/setup 3.0.0 → 3.0.2

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);
     }
 }