@mearl/setup 2.22.0 → 3.0.0-beta.0

package/dist/plugin.js

@@ -1,10 +1,11 @@
 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, findOfficialPlugin, findPluginEntry, findPluginRegistration, listPluginNames, loadPlugin, OFFICIAL_PLUGIN_MANAGER, registerPlugin, resolvePluginEntry, unregisterPlugin, } from '@mearl/client/plugin';
+import { assertPluginName, findPluginDirectoryEntry, readOfficialPluginCatalog, findPluginEntry, findPluginRegistration, listPluginNames, loadPlugin, OFFICIAL_PLUGIN_MANAGER, registerPlugin, resolvePluginEntry, unregisterPlugin, } from '@mearl/client/plugin';
+import { claimPresetInstallation } from './presetInstallationLease.js';
 import { ensurePluginRuntime } from './pluginRuntime.js';
-import { resolveAliSkillsInvocation, stripAnsi } from './aliSkills.js';
-import { findExecutable, prependNodePath, runCommand, } from '@mearl/daemon-core';
+import { captureSkillsCli, parseInstalledSkills, stripAnsi } from './skills.js';
+import { runCommand, withOwnedCommands, } from '@mearl/daemon-core';
 const registrationContext = {
     options: {},
     invoke: async () => {
@@ -47,22 +48,35 @@ export async function setupPlugin(target, requestedName) {
     };
 }
 export async function ensureOfficialPlugin(name, runner = runCommand) {
-    const definition = findOfficialPlugin(name);
+    const accepted = readOfficialPluginCatalog();
+    const definition = accepted?.plugins[name];
     if (!definition)
         throw new Error(`未知官方插件: ${name}`);
     if (findPluginRegistration(name))
         return 'existing';
-    const code = await installPlugins([...definition.installArgs], runner, {
-        registrationManagedBy: OFFICIAL_PLUGIN_MANAGER,
-    });
-    if (code !== 0)
-        throw new Error(`官方插件 ${name} 安装失败 (exit ${code})`);
-    const registration = findPluginRegistration(name);
-    if (!registration)
-        throw new Error(`官方插件 ${name} 安装完成后仍未注册`);
-    return 'installed';
+    const lease = claimPresetInstallation();
+    try {
+        return await withOwnedCommands(lease.lifecycle, async () => {
+            const code = await installPlugins([...definition.installArgs], runner, {
+                registrationManagedBy: OFFICIAL_PLUGIN_MANAGER,
+                selection: accepted.selection,
+                ...(accepted.selection ? { expectedSkill: definition.skill, expectedPluginName: name } : {}),
+                confirm: () => { if (JSON.stringify(readOfficialPluginCatalog()) !== JSON.stringify(accepted))
+                    throw new Error('PLUGIN_CATALOG_SELECTION_CHANGED'); },
+            });
+            if (code !== 0)
+                throw new Error(`官方插件 ${name} 安装失败 (exit ${code})`);
+            const registration = findPluginRegistration(name);
+            if (!registration)
+                throw new Error(`官方插件 ${name} 安装完成后仍未注册`);
+            return 'installed';
+        });
+    }
+    finally {
+        lease.release();
+    }
 }
-function globalAliSkill(entry) {
+function globalSkill(entry) {
     const globalSkillsDirectory = join(homedir(), '.agents', 'skills');
     const relativeEntry = relative(globalSkillsDirectory, resolve(entry));
     if (!isAbsolute(relativeEntry) &&
@@ -96,8 +110,8 @@ function globalAliSkill(entry) {
     }
     return undefined;
 }
-function projectAliSkill(entry, managedBy) {
-    if (managedBy !== 'ali-skills')
+function projectSkill(entry, managedBy) {
+    if (managedBy !== 'skills' && managedBy !== 'ali-skills')
         return undefined;
     const absolute = resolve(entry);
     const marker = `${sep}.agents${sep}skills${sep}`;
@@ -117,13 +131,13 @@ function projectAliSkill(entry, managedBy) {
         return undefined;
     return { directory: join(cwd, '.agents', 'skills', name), name, cwd };
 }
-export async function uninstallPlugin(name, runner = runCommand) {
+export async function uninstallPlugin(name, runner = runCommand, options = {}) {
     assertPluginName(name);
     const entry = findPluginEntry(name);
     if (!entry)
         return { removed: false, unregisteredNames: [] };
     const entryMissing = !existsSync(entry);
-    const managedSkill = projectAliSkill(entry, findPluginRegistration(name)?.managedBy) ?? globalAliSkill(entry);
+    const managedSkill = projectSkill(entry, findPluginRegistration(name)?.managedBy) ?? globalSkill(entry);
     if (!managedSkill) {
         unregisterPlugin(name);
         return {
@@ -132,22 +146,26 @@ export async function uninstallPlugin(name, runner = runCommand) {
             unregisteredNames: [name],
         };
     }
-    const invocation = resolveAliSkillsInvocation();
-    if (!invocation)
-        throw new Error('未找到 ali-skills 或 npx，插件注册已保留。');
     const { directory: skillDirectory, name: skillName } = managedSkill;
     const unregisteredNames = listPluginNames().filter(pluginName => {
         try {
             const candidate = findPluginEntry(pluginName);
             if (!candidate)
                 return false;
-            const candidateSkill = projectAliSkill(candidate, 'ali-skills') ?? globalAliSkill(candidate);
+            const candidateSkill = projectSkill(candidate, 'skills') ?? globalSkill(candidate);
             return candidateSkill?.directory === skillDirectory;
         }
         catch {
             return false;
         }
     });
+    if (options.preserveRegistrationsOutsideManager && unregisteredNames.some(pluginName => findPluginRegistration(pluginName)?.managedBy !== options.preserveRegistrationsOutsideManager)) {
+        unregisterPlugin(name);
+        return { removed: true, unregisteredNames: [name] };
+    }
+    const cli = await captureSkillsCli({ env: options.env, runCommand: runner });
+    if (!cli)
+        throw new Error('未找到 skills 或 npx，插件注册已保留。');
     let placeholderCreated = false;
     if (!existsSync(skillDirectory)) {
         mkdirSync(dirname(skillDirectory), { recursive: true, mode: 0o700 });
@@ -162,16 +180,15 @@ export async function uninstallPlugin(name, runner = runCommand) {
     }
     let removed;
     try {
-        removed = await runner(invocation.command, [
-            ...invocation.argsPrefix,
+        removed = await cli.run([
             'remove',
             skillName,
             ...(managedSkill.cwd ? [] : ['--global']),
             '--yes',
-        ], { env: invocation.env, tee: true, ...(managedSkill.cwd ? { cwd: managedSkill.cwd } : {}) });
+        ], { tee: true, ...(managedSkill.cwd ? { cwd: managedSkill.cwd } : {}) });
     }
     catch (error) {
-        throw new Error(`ali-skills remove ${skillName} 执行失败：${error instanceof Error ? error.message : String(error)}；插件注册已保留。`, { cause: error });
+        throw new Error(`skills remove ${skillName} 执行失败：${error instanceof Error ? error.message : String(error)}；插件注册已保留。`, { cause: error });
     }
     finally {
         if (placeholderCreated) {
@@ -179,12 +196,15 @@ export async function uninstallPlugin(name, runner = runCommand) {
                 rmdirSync(skillDirectory);
             }
             catch {
-                /* ali-skills 已移除，或目录中出现了新内容。 */
+                /* skills 已移除，或目录中出现了新内容。 */
             }
         }
     }
     if (removed.code !== 0) {
-        throw new Error(`ali-skills remove ${skillName} 失败（exit ${removed.code}）；插件注册已保留。`);
+        throw new Error(`skills remove ${skillName} 失败（exit ${removed.code}）；插件注册已保留。`);
+    }
+    if (/Failed to remove\s+[1-9]\d*\s+skills?/i.test(stripAnsi(`${removed.stdout}\n${removed.stderr}`)) || existsSync(skillDirectory)) {
+        throw new Error(`skills remove ${skillName} 未完成；插件注册已保留。`);
     }
     for (const pluginName of unregisteredNames)
         unregisterPlugin(pluginName);
@@ -195,8 +215,8 @@ export async function uninstallPlugin(name, runner = runCommand) {
         unregisteredNames,
     };
 }
-/** Ali Skills 的 Installed 区块列出成功路径；计数校验避免输出变化导致漏注册。 */
-export function parseInstalledPluginPaths(output) {
+/** Skills 的 Installed 区块列出成功路径；计数校验避免输出变化导致漏注册。 */
+export function parseInstalledPluginPaths(output, listed = []) {
     const paths = [];
     let expected = 0;
     let inResult = false;
@@ -217,14 +237,19 @@ export function parseInstalledPluginPaths(output) {
         if (!item)
             continue;
         const value = item[1].trim().replaceAll('\\', '/');
-        const skillPath = resolve(value.startsWith('~/') ? join(homedir(), value.slice(2)) : value);
+        const copied = value.match(/^(.+?) \(copied\)$/);
+        const matches = copied ? listed.filter(skill => skill.scope === 'global' && skill.name === copied[1]) : [];
+        if (copied && matches.length !== 1)
+            throw new Error('无法从 Skills JSON 清单确认复制的 Skill 安装路径。');
+        const installedPath = copied ? matches[0].path : value;
+        const skillPath = resolve(installedPath.startsWith('~/') ? join(homedir(), installedPath.slice(2)) : installedPath);
         if (dirname(skillPath) !== join(homedir(), '.agents', 'skills')) {
             throw new Error(`无法识别全局 skill 安装路径: ${item[1]}。请使用 setup plugin [name] <path> 注册。`);
         }
         paths.push(skillPath);
     }
     if (paths.length !== expected)
-        throw new Error('Ali Skills 安装结果格式无法识别，请使用 setup plugin [name] <path> 注册。');
+        throw new Error('Skills 安装结果格式无法识别，请使用 setup plugin [name] <path> 注册。');
     return [...new Set(paths)];
 }
 function permitsEmptyInstallResult(args, output) {
@@ -234,24 +259,51 @@ function permitsEmptyInstallResult(args, output) {
 }
 export async function installPlugins(args, runner = runCommand, options = {}) {
     if (args.includes('--')) {
-        throw new Error('plugin install 不支持 -- 参数分隔符，以确保全局 symlink 安装选项生效。');
+        throw new Error('plugin install 不支持 -- 参数分隔符，以确保全局安装选项生效。');
     }
-    const npx = findExecutable('npx', { extraDirectories: [dirname(process.execPath)] });
-    if (!npx)
-        throw new Error('未找到 npx，请检查 Node.js 安装。');
-    // 固定共享安装模式，确保成功结果指向 ~/.agents/skills 中的入口。
-    const installed = await runner(npx, ['-y', 'ali-skills', 'add', ...args, '--global', '--install-mode', 'symlink'], {
-        env: prependNodePath(),
-        tee: true,
-    });
+    const cli = await captureSkillsCli({ env: options.env, runCommand: runner });
+    if (!cli)
+        throw new Error('未找到 skills 或 npx，请检查 Node.js 安装。');
+    if (options.selection && (cli.selection?.path !== options.selection.path || cli.selection.sha256 !== options.selection.sha256))
+        throw new Error('PLUGIN_CATALOG_SELECTION_CHANGED');
+    const declaration = options.expectedSkill ? cli.managedSkills[options.expectedSkill] : undefined;
+    if (options.expectedSkill && (!declaration?.source || declaration.source !== args[0]))
+        throw new Error('PLUGIN_CATALOG_SKILL_UNDECLARED');
+    const verifySkill = (registered = false) => {
+        if (!options.expectedSkill || !declaration)
+            return;
+        const status = cli.inspectGlobal(declaration.source, options.expectedSkill, declaration.version);
+        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);
+        if (status.state === 'conflict')
+            throw new Error(`${status.reason}: ${options.expectedSkill}`);
+    }
+    await options.confirm?.();
+    const installed = await cli.run(['add', ...args, '--global'], { tee: true });
     if (installed.code !== 0)
         return installed.code;
+    await options.confirm?.();
     const output = `${installed.stdout ?? ''}\n${installed.stderr ?? ''}`;
-    const paths = parseInstalledPluginPaths(output);
+    let listed = [];
+    if (/✓[^\n]*\(copied\)/.test(stripAnsi(output))) {
+        const result = await cli.run(['list', '--global', '--json'], { capture: true });
+        if (result.code !== 0)
+            throw new Error('无法读取 Skills JSON 清单；插件尚未注册。');
+        listed = parseInstalledSkills(result.stdout);
+    }
+    const paths = parseInstalledPluginPaths(output, listed);
+    if (options.expectedSkill) {
+        if (paths.length !== 1 || paths[0] !== join(homedir(), '.agents', 'skills', options.expectedSkill))
+            throw new Error('PLUGIN_CATALOG_SKILL_RESULT_MISMATCH');
+        verifySkill();
+    }
     if (paths.length === 0) {
         if (permitsEmptyInstallResult(args, output))
             return 0;
-        throw new Error('Ali Skills 安装成功但无法识别安装结果，请使用 setup plugin [name] <path> 注册。');
+        throw new Error('Skills 安装成功但无法识别安装结果，请使用 setup plugin [name] <path> 注册。');
     }
     const plugins = new Map();
     for (const skillPath of paths) {
@@ -263,6 +315,8 @@ export async function installPlugins(args, runner = runCommand, options = {}) {
         const plugin = await loadPlugin(entry, registrationContext);
         const name = plugin.name || basename(skillPath);
         assertPluginName(name);
+        if (options.expectedPluginName && name !== options.expectedPluginName)
+            throw new Error('PLUGIN_CATALOG_ALIAS_MISMATCH');
         if (plugins.has(name))
             throw new Error(`多个 skill 使用插件名称 ${name}，请调整入口的 name metadata。`);
         plugins.set(name, {
@@ -280,14 +334,22 @@ export async function installPlugins(args, runner = runCommand, options = {}) {
     }
     await ensurePluginRuntime(runner);
     for (const [name, { entry, description, toolbox, appProfiles, profileSources, hasPublicCommands },] of plugins) {
+        await options.confirm?.();
+        verifySkill();
+        const existing = findPluginRegistration(name);
+        if (options.registrationManagedBy && existing && existing.managedBy !== options.registrationManagedBy) {
+            console.error(`Plugin ${name}: existing user registration kept.`);
+            continue;
+        }
         registerPlugin(name, entry, description, {
             hasPublicCommands,
-            managedBy: options.registrationManagedBy,
+            managedBy: options.registrationManagedBy ?? (cli.id === 'skills' ? undefined : cli.id),
             ...(toolbox ? { toolbox } : {}),
             appProfiles,
             profileSources,
         });
         console.error(`Plugin ${name} registered: ${entry}${hasPublicCommands ? `\nRun: mearl ${name} --help` : toolbox ? '\nOpen in Mearl toolbox.' : ''}`);
     }
+    verifySkill(true);
     return 0;
 }

package/dist/preset.d.ts

@@ -0,0 +1,94 @@
+import { invoke } from '@mearl/client/local';
+import { type JsonObject } from '@mearl/preset';
+import { type BundleLoader } from '@mearl/preset/bundles';
+import { PresetInstallationStore } from './presetStore.js';
+export { claimPresetInstallation } from './presetInstallationLease.js';
+export { PresetInstallationStore, presetSelectionRevision } from './presetStore.js';
+export type { PresetInstallReceipt } from './presetStore.js';
+export { PresetBrowserTransfer } from './presetBrowserTransfer.js';
+export interface PresetHostTarget {
+    id: string;
+    socketPath?: string;
+}
+export interface PresetHostStatus {
+    id: string;
+    state: 'active' | 'pending' | 'rejected';
+    error?: string;
+}
+export interface PresetBrowserHostStatus extends PresetHostStatus {
+    settingsReady: boolean;
+}
+export interface PresetComponentStatus {
+    kind: 'skills' | 'providers';
+    id: string;
+    state: 'ready' | 'pending' | 'conflict';
+    reason?: string;
+}
+export interface PresetComponentHostStatus {
+    installationRevision: string;
+    nodeRevision: string;
+    components: PresetComponentStatus[];
+    catalogReady?: boolean;
+}
+export interface PresetInstallStatus {
+    revision: string | null;
+    id?: string;
+    version?: string;
+    ready: boolean;
+    settings?: JsonObject;
+    overrides?: JsonObject;
+    nodeRevision?: string;
+    browserRevision?: string;
+    browserSyncRequired?: boolean;
+    localComponentCount?: number;
+    hosts: PresetHostStatus[];
+    browsers: PresetBrowserHostStatus[];
+    pending: Array<{
+        kind: 'preset' | 'packages' | 'skills' | 'providers';
+        id: string;
+        runtime: 'browser' | 'node';
+        reason: string;
+    }>;
+    warnings: string[];
+}
+export interface PresetInstallerOptions {
+    directory?: string;
+    mearlApiVersion?: string;
+    load?: BundleLoader;
+    hosts?: () => PresetHostTarget[];
+    invoke?: typeof invoke;
+}
+export interface PresetApplyOptions {
+    overrides?: JsonObject;
+    nodeConfig?: Record<string, JsonObject>;
+    signal?: AbortSignal;
+    expectedRevision?: string | null;
+    expectedId?: string;
+    confirm?: () => Promise<void>;
+}
+export interface StagedPresetInstallation {
+    revision: string;
+    activate: () => Promise<PresetInstallStatus>;
+}
+/** The caller chooses the source; this loader adds no identity or credential discovery. */
+export declare function createNodePresetLoader(): BundleLoader;
+/** Installation and live acknowledgements are distinct; browser/external installs remain pending. */
+export declare class PresetInstaller {
+    readonly store: PresetInstallationStore;
+    private readonly options;
+    constructor(options?: PresetInstallerOptions);
+    private invokeHost;
+    private hostStatus;
+    private browserStatus;
+    private componentStatus;
+    status(): Promise<PresetInstallStatus>;
+    private synchronize;
+    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>;
+    update(): Promise<PresetInstallStatus>;
+    resume(expectedRevision: string): Promise<PresetInstallStatus>;
+    configure(value: JsonObject): Promise<PresetInstallStatus>;
+}
+export declare function runPresetCommand(command: 'apply' | 'update' | 'status', source?: string): Promise<PresetInstallStatus>;

package/dist/preset.js

@@ -0,0 +1,275 @@
+import { lstat, open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+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';
+export { claimPresetInstallation } from './presetInstallationLease.js';
+export { PresetInstallationStore, presetSelectionRevision } from './presetStore.js';
+export { PresetBrowserTransfer } from './presetBrowserTransfer.js';
+/** The caller chooses the source; this loader adds no identity or credential discovery. */
+export function createNodePresetLoader() {
+    const network = createBundleFetchLoader();
+    return async (source, options) => {
+        const url = new URL(source);
+        if (url.protocol === 'file:') {
+            options.signal?.throwIfAborted();
+            const file = fileURLToPath(url);
+            const before = await lstat(file);
+            if (!before.isFile() || before.isSymbolicLink() || before.size > options.maxBytes)
+                throw new BundleError('BUNDLE_QUOTA', 'Invalid local preset resource file or size');
+            const handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+            try {
+                const stat = await handle.stat();
+                if (!stat.isFile() || stat.size > options.maxBytes)
+                    throw new BundleError('BUNDLE_QUOTA', 'Local preset resource exceeds its size limit');
+                const bytes = Buffer.alloc(stat.size + 1);
+                let length = 0;
+                while (length < bytes.byteLength) {
+                    options.signal?.throwIfAborted();
+                    const result = await handle.read(bytes, length, bytes.byteLength - length, null);
+                    if (!result.bytesRead)
+                        break;
+                    length += result.bytesRead;
+                }
+                if (length > stat.size)
+                    throw new BundleError('BUNDLE_INTEGRITY', 'Local preset resource changed while reading');
+                return bytes.subarray(0, length);
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        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);
+    };
+}
+function sourceUrl(source) {
+    try {
+        return new URL(source).href;
+    }
+    catch {
+        return pathToFileURL(resolve(source)).href;
+    }
+}
+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 }) }];
+}
+/** Installation and live acknowledgements are distinct; browser/external installs remain pending. */
+export class PresetInstaller {
+    store;
+    options;
+    constructor(options = {}) {
+        this.options = options;
+        this.store = new PresetInstallationStore(options);
+    }
+    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 });
+    }
+    async hostStatus(reload, nodeRevision, installationRevision) {
+        const 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' };
+            }
+            catch {
+                return { id: target.id, state: 'pending', error: 'HOST_UNAVAILABLE' };
+            }
+        }));
+    }
+    async browserStatus(reload, browserRevision, installationRevision) {
+        const targets = 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: result?.ready === true && result?.browserRevision === browserRevision && result?.installationRevision === installationRevision ? 'active' : 'pending', settingsReady: result?.settingsReady === true };
+            }
+            catch {
+                return { id: target.id, state: 'pending', settingsReady: false, error: 'BROWSER_UNAVAILABLE' };
+            }
+        }));
+    }
+    async componentStatus(install, receipt) {
+        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);
+            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'))
+                    throw new Error('Invalid component installation status');
+                const key = `${entry.kind}:${entry.id}`;
+                if (seen.has(key))
+                    throw new Error('Duplicate component installation status');
+                seen.add(key);
+            }
+            return { status: result };
+        }
+        catch (error) {
+            return { error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    async status() {
+        const current = await this.store.current();
+        const result = { revision: presetSelectionRevision(current), ready: false, hosts: [], browsers: [], pending: [], warnings: [] };
+        if (!current.receipt || !current.prepared)
+            return result;
+        const { preset } = current.prepared;
+        const receipt = current.receipt;
+        result.id = preset.id;
+        result.version = preset.version;
+        result.overrides = receipt.overrides;
+        result.settings = mergePresetDefaults(preset.defaults, receipt.overrides);
+        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
+            + [...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)
+            result.browsers = await this.browserStatus(false, receipt.browserRevision, receipt.revision);
+        const browserReady = result.browsers.length > 0 && result.browsers.every(host => host.state === 'active');
+        for (const [id, entry] of Object.entries(preset.packages)) {
+            if (entry.enabled === false)
+                continue;
+            for (const runtime of entry.runtimes ?? []) {
+                if (runtime === 'browser') {
+                    if (!browserReady)
+                        result.pending.push({ kind: 'packages', id, runtime, reason: 'BROWSER_SYNC_REQUIRED' });
+                }
+                else if (!receipt.managedModules.includes(id))
+                    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' });
+            }
+        }
+        const hasExternal = ['skills', 'providers'].some(kind => Object.values(preset[kind]).some(entry => entry.enabled !== false));
+        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' });
+        if (components.error)
+            result.warnings.push(`Component readiness check failed: ${components.error}`);
+        for (const kind of ['skills', 'providers'])
+            for (const [id, entry] of Object.entries(preset[kind])) {
+                if (entry.enabled === false)
+                    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' });
+            }
+        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 (receipt.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 (receipt.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;
+    }
+    async synchronize(receipt, previousRevision) {
+        const hosts = await this.hostStatus(true, receipt.nodeRevision, receipt.revision);
+        const rejection = hosts.find(host => host.state === 'rejected');
+        if (rejection) {
+            if (previousRevision === receipt.revision)
+                throw new Error(`Node activation rejected; installed selection retained: ${rejection.error}`);
+            await this.store.rollback(receipt.revision);
+            const previous = await this.store.current({ verifyResources: false });
+            await this.hostStatus(true, previous.activation?.revision ?? '', previous.activation?.installationRevision ?? '');
+            throw new Error(`Node activation rejected; previous selection restored: ${rejection.error}`);
+        }
+        if (receipt.browserSyncRequired) {
+            const browsers = await this.browserStatus(true, receipt.browserRevision, receipt.revision);
+            const rejected = browsers.find(host => host.state === 'rejected');
+            if (rejected)
+                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) : {};
+        const status = await this.status();
+        if (components.error)
+            status.warnings.push(`Component installation failed; completed assets retained for retry: ${components.error}`);
+        if (status.revision !== receipt.revision)
+            throw new BundleError('BUNDLE_CONFLICT', 'The selected preset changed while hosts were synchronizing');
+        try {
+            await this.store.collectGarbage();
+        }
+        catch (error) {
+            status.warnings.push(`Preset resource cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        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 });
+        if (options.expectedId !== undefined && prepared.preset.id !== options.expectedId)
+            throw new BundleError('BUNDLE_INVALID', 'The preset identity differs from the accepted installation');
+        const receipt = await this.store.apply(prepared, { ...options, expectedRevision });
+        let activated = false;
+        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;
+                const current = await this.store.current();
+                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) }), ...(options.nodeConfig === undefined ? {} : { nodeConfig: mergePresetDefaults({}, options.nodeConfig) }) };
+        const current = await this.store.current({ verifyResources: false });
+        const revision = presetSelectionRevision(current);
+        if (accepted.expectedRevision !== undefined && accepted.expectedRevision !== revision)
+            throw new BundleError('BUNDLE_CONFLICT', 'The installed preset changed before preparation');
+        return this.stageSource(source, revision, accepted);
+    }
+    async apply(source, options = {}) {
+        return (await this.stage(source, options)).activate();
+    }
+    async update() {
+        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) });
+    }
+    async resume(expectedRevision) {
+        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);
+    }
+    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 });
+        return this.synchronize(receipt, presetSelectionRevision(current));
+    }
+}
+export async function runPresetCommand(command, source) {
+    const installer = new PresetInstaller();
+    return command === 'status' ? installer.status() : command === 'update' ? installer.update() : installer.apply(source);
+}