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

package/dist/lifecycle.js

@@ -1,6 +1,7 @@
 import { SETUP_VERSION } from './setupVersion.js';
 import fs from 'node:fs';
 import path from 'node:path';
+import { homedir } from 'node:os';
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import { listPluginNames } from '@mearl/client/plugin';
@@ -9,14 +10,17 @@ import { runGlobalMearlSkillOperation } from './skills.js';
 import { buildGlobalPackageCommand, detectGlobalPackage, resolveInvokingPackageManager, resolvePackageManagerInstallation, } from './packageManager.js';
 import { MEARL_PROFILES, detectMearlProfiles, } from './profiles.js';
 import { uninstallNativeHostArtifacts } from './nativeHost.js';
-import { executableNames, prependCommandPath, runCommand, } from '@mearl/daemon-core';
+import { executableNames, prependCommandPath, runCommand, withOwnedCommands, } from '@mearl/daemon-core';
+import { readInstallationManagement, setupManagementCommand, setupRuntimeCompatible } from '@mearl/daemon-core/installation';
+import { claimPresetInstallation } from './presetInstallationLease.js';
 import { isMearlReleaseLine, mearlPackageSelector } from './version.js';
 import { installManagedPlugins, uninstallManagedPlugins, } from './managedPlugins.js';
 import { uninstallPlugin } from './plugin.js';
 import { uninstallProviderPackage } from './provider.js';
 import { packageRegistryEnvironment } from './npmRegistry.js';
 import { cleanupUninstalledRuntime } from './runtimeCleanup.js';
-import { prepareSetupPreset } from './presetUpgrade.js';
+import { prepareSetupPreset } from './setupPreset.js';
+import { prepareBrowserSetupPreset } from './browserPreset.js';
 const LEGACY_CLOUD_CLIENT = '@mearl/cloud-client';
 const UNIFIED_CLIENT = '@mearl/client';
 const PROFILE_ORDER = ['local', 'cloud', 'mcp'];
@@ -135,12 +139,12 @@ async function runHook(profile, operation, detected, runner, existsSync, env, wr
                 return false;
             }
             const running = /\[CloudServer\]\s+Status:\s+running\b/.test(status.stdout);
-            const qoderMode = cloudMode === 'qoder' || /\[CloudServer\]\s+Mode:\s+qoder\b/.test(status.stdout);
-            if (operation === 'update' && !running && !qoderMode) {
+            const pluginMode = Boolean(cloudMode && cloudMode !== 'websocket') || /\[CloudServer\]\s+Mode:\s+(?!websocket\b)\S+/.test(status.stdout);
+            if (operation === 'update' && !running && !pluginMode) {
                 writeLine('Hook: cloud update skipped because cloud-server is not running.');
                 return true;
             }
-            args = [running && !qoderMode ? 'restart' : 'start'];
+            args = [running && !pluginMode ? 'restart' : 'start'];
         }
     }
     else {
@@ -175,6 +179,38 @@ export async function runMearlLifecycle(options, dependencies = {}) {
     if (options.targetLine && !isMearlReleaseLine(options.targetLine)) {
         throw new Error('targetLine must be a valid Mearl release line such as 2.3.x');
     }
+    const writeLine = dependencies.writeLine ?? (line => console.error(line));
+    let lease;
+    try {
+        lease = (dependencies.claimLifecycle ?? (() => claimPresetInstallation(path.join(homedir(), '.agents', '.mearl-setup-lifecycle.json'))))();
+        const readManagement = () => (dependencies.readManagement ?? readInstallationManagement)({ directory: (options.env ?? process.env).MEARL_CAPABILITY_DIR });
+        let acceptedRevision = (await readManagement()).revision;
+        let selector = mearlPackageSelector(SETUP_VERSION, options.targetLine);
+        const assertManagement = async (expected = acceptedRevision) => {
+            const { setup, revision } = await readManagement();
+            if (revision !== expected)
+                throw new Error('PRESET_SELECTION_CHANGED: The selected preset changed during setup.');
+            if (setup && options.operation !== 'uninstall' && !setupRuntimeCompatible(setup, SETUP_VERSION, options.targetLine)) {
+                throw new Error(`SETUP_RUNTIME_CONFLICT: The selected preset requires ${setup.runtime}. Use ${setupManagementCommand(setup)} ${options.operation}.`);
+            }
+            selector = setup?.runtime ? options.targetLine ?? SETUP_VERSION : mearlPackageSelector(SETUP_VERSION, options.targetLine);
+        };
+        await assertManagement();
+        const runner = dependencies.runCommand ?? runCommand;
+        return await withOwnedCommands(lease.lifecycle, () => executeLifecycle(options, {
+            ...dependencies,
+            runCommand: async (...args) => { await assertManagement(); return runner(...args); },
+        }, async (revision) => { await assertManagement(revision); acceptedRevision = revision; }, () => selector));
+    }
+    catch (error) {
+        writeLine(`Setup: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+    finally {
+        lease?.release();
+    }
+}
+async function executeLifecycle(options, dependencies, acceptPreset, packageSelector) {
     const env = options.env ?? process.env;
     const writeLine = dependencies.writeLine ?? (line => console.error(line));
     const existsSync = dependencies.existsSync ?? fs.existsSync;
@@ -281,17 +317,16 @@ export async function runMearlLifecycle(options, dependencies = {}) {
         ? detectPackage(UNIFIED_CLIENT, ['mearl'], packageDetectionOptions)
         : null;
     const detectedClient = detectedClientCandidate?.packageName === UNIFIED_CLIENT ? detectedClientCandidate : null;
+    const preparesPreset = options.operation !== 'uninstall' && !dependencies.prepareSkills && (!options.targetLine || Number(options.targetLine.split('.')[0]) >= 3);
+    const selectsInitialPreset = preparesPreset && !options.skipSkill && !env.MEARL_AUTO_UPDATE_CLIENT_ROOT && !env.MEARL_AUTO_UPDATE_PROFILES;
     let stagedPreset;
-    if (options.operation !== 'uninstall' && (options.presetSource || !options.targetLine || Number(options.targetLine.split('.')[0]) >= 3) && !dependencies.prepareSkills) {
+    if (preparesPreset || (options.operation !== 'uninstall' && options.presetSource && !dependencies.prepareSkills)) {
         try {
             stagedPreset = await (dependencies.preparePreset ?? prepareSetupPreset)({
                 source: options.presetSource, env,
-                installed: [
-                    ...lifecycleSelected.flatMap(profile => detected.get(profile) ? [detected.get(profile)] : []),
-                    ...(detectedClient ? [detectedClient] : []),
-                    ...(autoUpdateClient && env.MEARL_AUTO_UPDATE_CLIENT_ROOT ? [{ packageName: UNIFIED_CLIENT, packageRoot: env.MEARL_AUTO_UPDATE_CLIENT_ROOT }] : []),
-                ],
             });
+            if (stagedPreset)
+                await acceptPreset(stagedPreset.revision);
         }
         catch (error) {
             writeLine(`Preset preparation: ${error instanceof Error ? error.message : String(error)}`);
@@ -324,7 +359,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
             detected.get('local') ??
             detected.get('cloud') ??
             resolveInvokingManager(env);
-        const sharedClient = await runPackageOperation(clientInstallation, options.operation, [UNIFIED_CLIENT], mearlPackageSelector(SETUP_VERSION, options.targetLine), runner, env, 'Packages (shared client)', writeLine);
+        const sharedClient = await runPackageOperation(clientInstallation, options.operation, [UNIFIED_CLIENT], packageSelector(), runner, env, 'Packages (shared client)', writeLine);
         if (!sharedClient.ok) {
             writeLine('Mearl setup incomplete. Review the messages above.');
             return false;
@@ -364,7 +399,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
         if (packages.length === 0) {
             continue;
         }
-        const packageResult = await runPackageOperation(installation, packageOperation, packages, mearlPackageSelector(SETUP_VERSION, options.targetLine), runner, env, `Packages (${profile})`, writeLine);
+        const packageResult = await runPackageOperation(installation, packageOperation, packages, packageSelector(), runner, env, `Packages (${profile})`, writeLine);
         if (!packageResult.ok) {
             packagesOk = false;
             continue;
@@ -422,6 +457,28 @@ export async function runMearlLifecycle(options, dependencies = {}) {
             }
         }
     }
+    if (packagesOk && selectsInitialPreset && !stagedPreset && !options.presetSource && lifecycleSelected.some(profile => profile === 'local' || profile === 'mcp')) {
+        try {
+            stagedPreset = await (dependencies.prepareBrowserPreset ?? prepareBrowserSetupPreset)({ env, waitMs: 65_000, writeLine });
+            if (stagedPreset)
+                await acceptPreset(stagedPreset.revision);
+        }
+        catch (error) {
+            writeLine(`Browser preset: ${error instanceof Error ? error.message : String(error)}`);
+            packagesOk = false;
+        }
+    }
+    if (packagesOk && selectsInitialPreset && !stagedPreset && options.defaultPresetSource) {
+        try {
+            stagedPreset = await (dependencies.preparePreset ?? prepareSetupPreset)({ fallbackSource: options.defaultPresetSource, env });
+            if (stagedPreset)
+                await acceptPreset(stagedPreset.revision);
+        }
+        catch (error) {
+            writeLine(`Default preset: ${error instanceof Error ? error.message : String(error)}`);
+            packagesOk = false;
+        }
+    }
     if (packagesOk && options.operation !== 'uninstall' && (stagedPreset || dependencies.prepareSkills)) {
         try {
             if (stagedPreset) {

package/dist/plugin.d.ts

@@ -5,7 +5,7 @@ export interface PluginSetupResult {
     entry: string;
     name: string;
 }
-export declare function setupPlugin(target: string, requestedName?: string): Promise<PluginSetupResult>;
+export declare function setupPlugin(target: string, requestedName?: string, runner?: CommandRunner): Promise<PluginSetupResult>;
 export declare function ensureOfficialPlugin(name: string, runner?: CommandRunner): Promise<'existing' | 'installed'>;
 export interface PluginUninstallResult {
     entryMissing?: boolean;

package/dist/plugin.js

@@ -1,7 +1,8 @@
 import { existsSync, mkdirSync, readdirSync, readlinkSync, realpathSync, rmdirSync, statSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { assertPluginName, findPluginDirectoryEntry, readOfficialPluginCatalog, findPluginEntry, findPluginRegistration, listPluginNames, loadPlugin, OFFICIAL_PLUGIN_MANAGER, registerPlugin, resolvePluginEntry, unregisterPlugin, } from '@mearl/client/plugin';
+import { assertPluginName, findPluginDirectoryEntry, skillManifestPath, readOfficialPluginCatalog, findPluginEntry, findPluginRegistration, listPluginNames, loadPlugin, OFFICIAL_PLUGIN_MANAGER, registerPlugin, resolvePluginEntry, unregisterPlugin, } from '@mearl/client/plugin';
+import { preserveSkillDisabled } from './skillSources.js';
 import { claimPresetInstallation } from './presetInstallationLease.js';
 import { ensurePluginRuntime } from './pluginRuntime.js';
 import { captureSkillsCli, parseInstalledSkills, stripAnsi } from './skills.js';
@@ -29,14 +30,15 @@ function defaultPluginName(target, entry) {
         ? basename(dirname(entryDirectory))
         : basename(entryDirectory);
 }
-export async function setupPlugin(target, requestedName) {
+export async function setupPlugin(target, requestedName, runner = runCommand) {
     if (requestedName)
         assertPluginName(requestedName);
     const entry = resolvePluginEntry(target);
     const plugin = await loadPlugin(entry, registrationContext);
     const name = requestedName || plugin.name || defaultPluginName(target, entry);
     assertPluginName(name);
-    await ensurePluginRuntime();
+    await ensurePluginRuntime(runner);
+    await plugin.setup?.({ runCommand: runner });
     return {
         entry: registerPlugin(name, entry, plugin.description, {
             hasPublicCommands: Boolean(plugin.commandHelp(name)),
@@ -52,8 +54,22 @@ export async function ensureOfficialPlugin(name, runner = runCommand) {
     const definition = accepted?.plugins[name];
     if (!definition)
         throw new Error(`未知官方插件: ${name}`);
-    if (findPluginRegistration(name))
-        return 'existing';
+    const existing = findPluginRegistration(name);
+    if (existing) {
+        if (!accepted.selection || existing.managedBy !== OFFICIAL_PLUGIN_MANAGER)
+            return 'existing';
+        const cli = await captureSkillsCli({ runCommand: runner });
+        if (!cli || cli.selection?.path !== accepted.selection.path || cli.selection.sha256 !== accepted.selection.sha256)
+            throw new Error('PLUGIN_CATALOG_SELECTION_CHANGED');
+        const declaration = cli.managedSkills[definition.skill];
+        if (!declaration?.source || declaration.source !== definition.installArgs[0])
+            throw new Error('PLUGIN_CATALOG_SKILL_UNDECLARED');
+        const status = cli.inspectGlobal(declaration.source, definition.skill, declaration.version, { migrateFrom: declaration.migrateFrom });
+        if (status.state === 'ready')
+            return 'existing';
+        if (status.state === 'conflict')
+            throw new Error(`${status.reason}: ${definition.skill}`);
+    }
     const lease = claimPresetInstallation();
     try {
         return await withOwnedCommands(lease.lifecycle, async () => {
@@ -276,13 +292,22 @@ export async function installPlugins(args, runner = runCommand, options = {}) {
         if (status.state !== 'ready' && (registered || status.state !== 'registration'))
             throw new Error(`${status.reason}: ${options.expectedSkill}`);
     };
-    if (options.expectedSkill && declaration) {
-        const status = cli.inspectGlobal(declaration.source, options.expectedSkill, declaration.version);
+    const assertSource = () => {
+        if (!options.expectedSkill || !declaration)
+            return;
+        const status = cli.inspectGlobal(declaration.source, options.expectedSkill, declaration.version, {
+            migrateFrom: options.registrationManagedBy === OFFICIAL_PLUGIN_MANAGER ? declaration.migrateFrom : undefined,
+        });
         if (status.state === 'conflict')
             throw new Error(`${status.reason}: ${options.expectedSkill}`);
-    }
+    };
+    assertSource();
     await options.confirm?.();
-    const installed = await cli.run(['add', ...args, '--global'], { tee: true });
+    assertSource();
+    const runInstall = () => cli.run(['add', ...args, '--global'], { tee: true });
+    const installed = await (options.expectedSkill
+        ? preserveSkillDisabled(join(homedir(), '.agents', 'skills', options.expectedSkill), runInstall)
+        : runInstall());
     if (installed.code !== 0)
         return installed.code;
     await options.confirm?.();
@@ -307,7 +332,7 @@ export async function installPlugins(args, runner = runCommand, options = {}) {
     }
     const plugins = new Map();
     for (const skillPath of paths) {
-        if (!statSync(join(skillPath, 'SKILL.md')).isFile())
+        if (!statSync(skillManifestPath(skillPath) ?? join(skillPath, 'SKILL.md')).isFile())
             throw new Error(`安装结果缺少 SKILL.md: ${skillPath}`);
         const entry = findPluginDirectoryEntry(skillPath);
         if (!entry)
@@ -321,6 +346,7 @@ export async function installPlugins(args, runner = runCommand, options = {}) {
             throw new Error(`多个 skill 使用插件名称 ${name}，请调整入口的 name metadata。`);
         plugins.set(name, {
             entry,
+            setup: plugin.setup,
             hasPublicCommands: Boolean(plugin.commandHelp(name)),
             description: plugin.description,
             ...(plugin.toolbox ? { toolbox: plugin.toolbox } : {}),
@@ -333,14 +359,26 @@ export async function installPlugins(args, runner = runCommand, options = {}) {
         return 0;
     }
     await ensurePluginRuntime(runner);
-    for (const [name, { entry, description, toolbox, appProfiles, profileSources, hasPublicCommands },] of plugins) {
+    for (const [name, { entry, description, toolbox, appProfiles, profileSources, hasPublicCommands, setup },] of plugins) {
         await options.confirm?.();
         verifySkill();
-        const existing = findPluginRegistration(name);
-        if (options.registrationManagedBy && existing && existing.managedBy !== options.registrationManagedBy) {
+        const hasUserRegistration = () => {
+            const existing = findPluginRegistration(name);
+            return options.registrationManagedBy && existing && existing.managedBy !== options.registrationManagedBy;
+        };
+        if (hasUserRegistration()) {
             console.error(`Plugin ${name}: existing user registration kept.`);
             continue;
         }
+        if (setup) {
+            await setup({ runCommand: runner });
+            await options.confirm?.();
+            verifySkill();
+            if (hasUserRegistration()) {
+                console.error(`Plugin ${name}: existing user registration kept.`);
+                continue;
+            }
+        }
         registerPlugin(name, entry, description, {
             hasPublicCommands,
             managedBy: options.registrationManagedBy ?? (cli.id === 'skills' ? undefined : cli.id),

package/dist/preset.d.ts

@@ -1,7 +1,10 @@
 import { invoke } from '@mearl/client/local';
 import { type JsonObject } from '@mearl/preset';
-import { type BundleLoader } from '@mearl/preset/bundles';
+import { type BundleLoader, type PreparedPreset } from '@mearl/preset/bundles';
 import { PresetInstallationStore } from './presetStore.js';
+export declare const MEARL_INSTALLATION_CONFIG_URL: string;
+/** Runtime overrides apply to this local process, never to browser-supplied install requests. */
+export declare function resolveInstallationConfigUrl(value?: string | undefined, allowLoopback?: boolean): URL;
 export { claimPresetInstallation } from './presetInstallationLease.js';
 export { PresetInstallationStore, presetSelectionRevision } from './presetStore.js';
 export type { PresetInstallReceipt } from './presetStore.js';
@@ -59,8 +62,9 @@ export interface PresetInstallerOptions {
     invoke?: typeof invoke;
 }
 export interface PresetApplyOptions {
+    validatePrepared?: (prepared: PreparedPreset) => Promise<void>;
+    skipUnchanged?: boolean;
     overrides?: JsonObject;
-    nodeConfig?: Record<string, JsonObject>;
     signal?: AbortSignal;
     expectedRevision?: string | null;
     expectedId?: string;
@@ -87,8 +91,15 @@ export declare class PresetInstaller {
     /** 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>;
-    update(): Promise<PresetInstallStatus>;
-    resume(expectedRevision: string): Promise<PresetInstallStatus>;
+    update(options?: Pick<PresetApplyOptions, 'validatePrepared' | 'skipUnchanged' | 'signal'>): Promise<PresetInstallStatus>;
+    resume(expectedRevision: string, options?: {
+        replaceSkills?: readonly string[];
+    }): Promise<PresetInstallStatus>;
+    repair(options?: {
+        replaceSkills?: readonly string[];
+    }): Promise<PresetInstallStatus>;
     configure(value: JsonObject): Promise<PresetInstallStatus>;
 }
-export declare function runPresetCommand(command: 'apply' | 'update' | 'status', source?: string): Promise<PresetInstallStatus>;
+export declare function runPresetCommand(command: 'apply' | 'update' | 'status' | 'repair', source?: string, options?: {
+    replaceSkills?: readonly string[];
+}): Promise<PresetInstallStatus>;

package/dist/preset.js

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

package/dist/presetStore.d.ts

@@ -1,48 +1,2 @@
-import { type JsonObject, type NodeCapabilityActivation, type ResolvedPreset } from '@mearl/preset';
-import { type PreparedBundle, type PreparedPreset, type PresetSnapshot } from '@mearl/preset/bundles';
-export interface PresetInstallReceipt {
-    schemaVersion: 1;
-    snapshot: PresetSnapshot;
-    bundles: Array<Omit<PreparedBundle, 'resources'>>;
-    browserRevision: string;
-    nodeRevision: string;
-    managedModules: string[];
-    nodeSyncRequired: boolean;
-    browserSyncRequired?: boolean;
-    nodeConfig: Record<string, JsonObject>;
-    overrides: JsonObject;
-    revision: string;
-}
-interface SelectionState {
-    rawHash: string | null;
-    activation?: NodeCapabilityActivation;
-    receipt?: PresetInstallReceipt;
-    prepared?: PreparedPreset;
-    preset?: ResolvedPreset;
-}
-/** One pointer binds the desired preset, user overrides and exact Node selection. */
-export declare class PresetInstallationStore {
-    readonly directory: string;
-    readonly mearlApiVersion: string;
-    private readonly pointer;
-    constructor(options?: {
-        directory?: string;
-        mearlApiVersion?: string;
-    });
-    private assertCurrent;
-    current(options?: {
-        verifyResources?: boolean;
-    }): Promise<SelectionState>;
-    apply(input: Pick<PreparedPreset, 'snapshot' | 'bundles'>, options: {
-        expectedRevision: string | null;
-        overrides?: JsonObject;
-        nodeConfig?: Record<string, JsonObject>;
-        signal?: AbortSignal;
-        confirm?: () => Promise<void>;
-    }): Promise<PresetInstallReceipt>;
-    rollback(expectedRevision: string): Promise<void>;
-    collectGarbage(): Promise<void>;
-    private collectLocked;
-}
-export declare function presetSelectionRevision(state: SelectionState): string | null;
-export {};
+export { PresetInstallationStore, presetSelectionRevision } from '@mearl/daemon-core/installation';
+export type { PresetInstallReceipt } from '@mearl/daemon-core/installation';