@mearl/setup 2.21.0 → 3.0.0-beta.0

package/dist/presetBrowserTransfer.d.ts

@@ -0,0 +1,11 @@
+import { type PresetTransferRequest } from '@mearl/preset/bundles';
+import { PresetInstallationStore } from './presetStore.js';
+/** One bounded, expiring transfer belongs to the host's attached extension connection. */
+export declare class PresetBrowserTransfer {
+    private readonly store;
+    private readonly now;
+    private session?;
+    constructor(store?: PresetInstallationStore, now?: () => number);
+    selectedRevision(acceptedNodeRevision: string | null | undefined): Promise<string | null>;
+    handle(input: PresetTransferRequest): Promise<unknown>;
+}

package/dist/presetBrowserTransfer.js

@@ -0,0 +1,72 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { BundleError, MAX_PRESET_TRANSFER_HEADER_BYTES, PRESET_TRANSFER_CHUNK_BYTES } from '@mearl/preset/bundles';
+import { PresetInstallationStore } from './presetStore.js';
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+/** One bounded, expiring transfer belongs to the host's attached extension connection. */
+export class PresetBrowserTransfer {
+    store;
+    now;
+    session;
+    constructor(store = new PresetInstallationStore(), now = Date.now) {
+        this.store = store;
+        this.now = now;
+    }
+    async selectedRevision(acceptedNodeRevision) {
+        const current = await this.store.current({ verifyResources: false });
+        return current.receipt?.browserSyncRequired && current.receipt.revision === acceptedNodeRevision ? current.receipt.revision : null;
+    }
+    async handle(input) {
+        if (!input || typeof input !== 'object')
+            throw new BundleError('BUNDLE_INVALID', 'Expected a browser transfer operation');
+        if (this.session && this.now() - this.session.touched > 120000)
+            this.session = undefined;
+        if (input.operation === 'open') {
+            if (this.session)
+                throw new BundleError('BUNDLE_CONFLICT', 'A browser preset transfer is already running');
+            if (typeof input.installationRevision !== 'string' || !/^[a-f0-9]{64}$/.test(input.installationRevision))
+                throw new BundleError('BUNDLE_INVALID', 'Expected an installation revision');
+            const current = await this.store.current();
+            if (!current.receipt || !current.prepared || current.receipt.revision !== input.installationRevision)
+                throw new BundleError('BUNDLE_CONFLICT', 'The selected preset changed before browser transfer');
+            const header = {
+                schemaVersion: 1, installationRevision: current.receipt.revision, snapshot: current.prepared.browser.snapshot,
+                bundles: current.prepared.browser.bundles.map(({ source, revision, manifest }) => ({ source, revision, manifest })),
+                overrides: current.receipt.overrides,
+            };
+            const bytes = Buffer.from(JSON.stringify(header));
+            if (bytes.byteLength > MAX_PRESET_TRANSFER_HEADER_BYTES)
+                throw new BundleError('BUNDLE_QUOTA', 'Browser transfer metadata exceeds 16 MiB');
+            const sha256 = digest(bytes);
+            const resources = new Map([[sha256, bytes]]);
+            for (const bundle of current.prepared.browser.bundles)
+                for (const [name, entry] of Object.entries(bundle.manifest.resources))
+                    resources.set(entry.sha256, bundle.resources[name]);
+            // A second open may finish validation while the first one is already streaming.
+            if (this.session)
+                throw new BundleError('BUNDLE_CONFLICT', 'A browser preset transfer is already running');
+            this.session = { id: randomUUID(), revision: current.receipt.revision, touched: this.now(), resources };
+            return { session: this.session.id, sha256, byteLength: bytes.byteLength };
+        }
+        const session = this.session;
+        if (!session || input.session !== session.id)
+            throw new BundleError('BUNDLE_CONFLICT', 'Browser preset transfer expired or changed');
+        session.touched = this.now();
+        if (input.operation === 'release') {
+            this.session = undefined;
+            return { released: true };
+        }
+        if (input.operation === 'confirm') {
+            const current = await this.store.current({ verifyResources: false });
+            if (current.receipt?.revision !== session.revision)
+                throw new BundleError('BUNDLE_CONFLICT', 'The selected preset changed during browser transfer');
+            return { installationRevision: session.revision };
+        }
+        if (input.operation === 'read') {
+            const bytes = session.resources.get(input.sha256);
+            if (!bytes || !Number.isSafeInteger(input.offset) || input.offset < 0 || input.offset >= bytes.byteLength || input.offset % PRESET_TRANSFER_CHUNK_BYTES !== 0)
+                throw new BundleError('BUNDLE_INVALID', 'Invalid browser transfer resource or offset');
+            return { data: Buffer.from(bytes.subarray(input.offset, input.offset + PRESET_TRANSFER_CHUNK_BYTES)).toString('base64') };
+        }
+        throw new BundleError('BUNDLE_INVALID', 'Unsupported browser preset transfer operation');
+    }
+}

package/dist/presetInstallationLease.d.ts

@@ -0,0 +1,6 @@
+import { type CommandLifecycle } from '@mearl/daemon-core';
+/** The owner covers the shared global Skills directory, including hosts with different presets. */
+export declare function claimPresetInstallation(file?: string): {
+    release(): void;
+    lifecycle: CommandLifecycle;
+};

package/dist/presetInstallationLease.js

@@ -0,0 +1,66 @@
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { isCommandProcessAlive, isProcessOwnerAlive, processIdentity, readRecord, withRecordLock } from '@mearl/daemon-core';
+/** The owner covers the shared global Skills directory, including hosts with different presets. */
+export function claimPresetInstallation(file = join(homedir(), '.agents', '.mearl-preset-install.json')) {
+    const owner = { pid: process.pid, token: randomUUID(), processIdentity: processIdentity(process.pid), active: true, children: [] };
+    const read = () => {
+        try {
+            return statSync(file).size <= 65536 ? readRecord(file) : null;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+    };
+    const write = (value) => {
+        const temporary = `${file}.${owner.token}.tmp`;
+        try {
+            writeFileSync(temporary, JSON.stringify(value), { mode: 0o600, flag: 'wx' });
+            renameSync(temporary, file);
+        }
+        finally {
+            rmSync(temporary, { force: true });
+        }
+    };
+    const owned = (value) => value?.token === owner.token && value.pid === owner.pid && value.processIdentity === owner.processIdentity;
+    withRecordLock(file, () => {
+        const previous = read();
+        if (previous && ((previous.active !== false && isProcessOwnerAlive(previous)) || previous.children?.some(isCommandProcessAlive)))
+            throw new Error('PRESET_INSTALL_BUSY');
+        write(owner);
+    });
+    return {
+        lifecycle: {
+            started(child) {
+                withRecordLock(file, () => {
+                    const current = read();
+                    if (!owned(current) || !current.active || current.children.length >= 256)
+                        throw new Error('PRESET_INSTALL_OWNER_CHANGED');
+                    write({ ...current, children: [...current.children, child] });
+                });
+            },
+            finished(child) {
+                withRecordLock(file, () => {
+                    const current = read();
+                    if (!owned(current))
+                        return;
+                    write({ ...current, children: current.children.filter(entry => entry.pid !== child.pid || entry.processIdentity !== child.processIdentity) });
+                });
+            },
+        },
+        release: () => withRecordLock(file, () => {
+            const current = read();
+            if (!owned(current))
+                return;
+            const children = current.children.filter(isCommandProcessAlive);
+            if (children.length)
+                write({ ...current, active: false, children });
+            else
+                rmSync(file, { force: true });
+        }),
+    };
+}

package/dist/presetStore.d.ts

@@ -0,0 +1,48 @@
+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 {};

package/dist/presetStore.js

@@ -0,0 +1,252 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants, closeSync, fstatSync, lstatSync, linkSync, mkdirSync, openSync, readSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { withRecordLock } from '@mearl/daemon-core';
+import { mergePresetDefaults, prepareNodeBundleSnapshot, prepareNodeCapabilitySnapshot, verifyNodeCapabilityActivation, validateNodeModuleConfig, resolvePresetModuleConfig, MAX_NODE_SELECTION_BYTES } from '@mearl/preset';
+import { BundleError, MAX_BROWSER_STORAGE_BYTES, presetRequiresBrowser, validateBundleManifest, verifyPreset, verifyBrowserPreset, verifyPreparedPreset } from '@mearl/preset/bundles';
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const hashPattern = /^[a-f0-9]{64}$/;
+const MAX_RECEIPT_BYTES = 16 * 1024 * 1024;
+const MAX_OVERRIDES_BYTES = 262_144;
+const POINTER_BYTES = MAX_NODE_SELECTION_BYTES + 128;
+function readBounded(file, limit) {
+    const before = lstatSync(file);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > limit)
+        throw new Error('Invalid preset resource file or size');
+    const descriptor = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const stat = fstatSync(descriptor);
+        if (!stat.isFile() || stat.size > limit)
+            throw new Error('Invalid preset resource file or size');
+        const bytes = Buffer.alloc(Math.min(stat.size, limit) + 1);
+        let length = 0;
+        while (length < bytes.byteLength) {
+            const count = readSync(descriptor, bytes, length, bytes.byteLength - length, null);
+            if (count === 0)
+                break;
+            length += count;
+        }
+        if (length > stat.size)
+            throw new Error('Preset resource changed while reading');
+        return bytes.subarray(0, length);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function optionalFile(file, limit) {
+    try {
+        return readBounded(file, limit);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+function atomicWrite(file, bytes) {
+    const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, bytes, { flag: 'wx', mode: 0o600 });
+        renameSync(temporary, file);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+function revision(state) {
+    return state.activation?.installationRevision ?? (state.activation ? `node:${state.activation.revision}` : null);
+}
+function overrides(value) {
+    const accepted = mergePresetDefaults({}, value);
+    if (Buffer.byteLength(JSON.stringify(accepted)) > MAX_OVERRIDES_BYTES)
+        throw new BundleError('BUNDLE_QUOTA', 'User overrides exceed 256 KiB');
+    return accepted;
+}
+/** One pointer binds the desired preset, user overrides and exact Node selection. */
+export class PresetInstallationStore {
+    directory;
+    mearlApiVersion;
+    pointer;
+    constructor(options = {}) {
+        this.directory = resolve(options.directory ?? (process.env.MEARL_CAPABILITY_DIR || join(homedir(), '.mearl/capabilities')));
+        this.mearlApiVersion = options.mearlApiVersion ?? '1.0.0';
+        this.pointer = join(this.directory, 'active-node.json');
+    }
+    assertCurrent(expected) {
+        const bytes = optionalFile(this.pointer, POINTER_BYTES);
+        if ((bytes ? digest(bytes) : null) !== expected)
+            throw new BundleError('BUNDLE_CONFLICT', 'The installed preset changed during preparation');
+    }
+    async current(options = {}) {
+        const raw = optionalFile(this.pointer, POINTER_BYTES);
+        if (!raw)
+            return { rawHash: null };
+        const rawHash = digest(raw);
+        const activation = await verifyNodeCapabilityActivation(JSON.parse(raw.toString('utf8')));
+        if (!activation.installationRevision)
+            return { rawHash, activation };
+        const captured = withRecordLock(this.pointer, () => {
+            this.assertCurrent(rawHash);
+            const receiptBytes = readBounded(join(this.directory, 'installations', `${activation.installationRevision}.json`), MAX_RECEIPT_BYTES);
+            const receipt = JSON.parse(receiptBytes.toString('utf8'));
+            const { revision: receiptRevision, ...data } = receipt;
+            if (receiptRevision !== activation.installationRevision || digest(JSON.stringify(data)) !== receiptRevision || data.schemaVersion !== 1 ||
+                Object.keys(data).some(key => !['schemaVersion', 'snapshot', 'bundles', 'browserRevision', 'nodeRevision', 'managedModules', 'nodeSyncRequired', 'browserSyncRequired', 'nodeConfig', 'overrides'].includes(key)) || typeof data.nodeSyncRequired !== 'boolean' || (data.browserSyncRequired !== undefined && typeof data.browserSyncRequired !== 'boolean') ||
+                data.nodeRevision !== activation.revision || !Array.isArray(data.bundles) || data.bundles.length > 64 ||
+                !Array.isArray(data.managedModules) || new Set(data.managedModules).size !== data.managedModules.length || data.managedModules.some(id => typeof id !== 'string' || !Object.hasOwn(activation.modules, id))) {
+                throw new BundleError('BUNDLE_INTEGRITY', 'Installed preset receipt does not match its selection');
+            }
+            const acceptedOverrides = overrides(data.overrides);
+            const nodeConfig = validateNodeModuleConfig(data.nodeConfig);
+            let total = 0;
+            const metadata = data.bundles.map(bundle => {
+                if (Object.keys(bundle).some(key => !['source', 'manifest', 'revision'].includes(key)))
+                    throw new BundleError('BUNDLE_INVALID', 'Invalid installed package metadata');
+                const manifest = validateBundleManifest(bundle.manifest, this.mearlApiVersion);
+                total += Object.values(manifest.resources).reduce((sum, entry) => sum + entry.byteLength, 0);
+                return { ...bundle, manifest };
+            });
+            if (total > MAX_BROWSER_STORAGE_BYTES)
+                throw new BundleError('BUNDLE_QUOTA', 'Installed preset resources exceed 64 MiB');
+            const bundles = options.verifyResources === false ? [] : metadata.map(bundle => ({ ...bundle, resources: Object.fromEntries(Object.entries(bundle.manifest.resources).map(([name, entry]) => [name, readBounded(join(this.directory, 'blobs', `${entry.sha256}.bin`), entry.byteLength)])) }));
+            for (const entry of options.verifyResources === false ? [] : Object.values(activation.modules)) {
+                const bytes = readBounded(join(this.directory, 'objects', `${entry.sha256}.cjs`), entry.byteLength);
+                if (bytes.byteLength !== entry.byteLength || digest(bytes) !== entry.sha256)
+                    throw new BundleError('BUNDLE_INTEGRITY', 'Installed Node object is missing or corrupt');
+            }
+            return { receipt: { ...receipt, overrides: acceptedOverrides, nodeConfig }, bundles };
+        });
+        if (options.verifyResources === false) {
+            const graph = await verifyPreset(captured.receipt.snapshot, this.mearlApiVersion);
+            await verifyBrowserPreset({ source: graph.snapshot.source, manifests: graph.snapshot.manifests,
+                bundleRevisions: Object.fromEntries(Object.entries(graph.snapshot.bundleRevisions).filter(([id]) => graph.preset.packages[id].runtimes?.includes('browser'))), revision: captured.receipt.browserRevision }, this.mearlApiVersion);
+            return { rawHash, activation, receipt: captured.receipt, preset: graph.preset };
+        }
+        const prepared = await verifyPreparedPreset({ snapshot: captured.receipt.snapshot, bundles: captured.bundles }, this.mearlApiVersion);
+        if (prepared.browser.snapshot.revision !== captured.receipt.browserRevision)
+            throw new BundleError('BUNDLE_INTEGRITY', 'Installed browser projection does not match');
+        const selected = await prepareNodeBundleSnapshot(prepared.bundles.filter(bundle => prepared.preset.packages[bundle.manifest.id].runtimes?.includes('node')), 'native-host', this.mearlApiVersion, resolvePresetModuleConfig(mergePresetDefaults(prepared.preset.defaults, captured.receipt.overrides), captured.receipt.nodeConfig));
+        if (Object.keys(selected.snapshot.modules).length !== captured.receipt.managedModules.length || captured.receipt.managedModules.some(id => !Object.hasOwn(selected.snapshot.modules, id)) ||
+            Object.entries(selected.snapshot.modules).some(([id, entry]) => JSON.stringify(entry) !== JSON.stringify(activation.modules[id])) ||
+            Object.entries(selected.snapshot.bindings).some(([hook, entry]) => JSON.stringify(entry) !== JSON.stringify(activation.bindings[hook])) ||
+            Object.values(activation.bindings).filter(entry => captured.receipt.managedModules.includes(entry.module)).length !== Object.keys(selected.snapshot.bindings).length) {
+            throw new BundleError('BUNDLE_INTEGRITY', 'Installed managed Node selection does not match its packages');
+        }
+        return { rawHash, activation, prepared, receipt: captured.receipt, preset: prepared.preset };
+    }
+    async apply(input, options) {
+        options.signal?.throwIfAborted();
+        const acceptedOverrides = options.overrides === undefined ? undefined : overrides(options.overrides);
+        const nodeConfig = options.nodeConfig === undefined ? undefined : validateNodeModuleConfig(options.nodeConfig);
+        const [current, prepared] = await Promise.all([this.current({ verifyResources: false }), verifyPreparedPreset(input, this.mearlApiVersion)]);
+        if (revision(current) !== options.expectedRevision)
+            throw new BundleError('BUNDLE_CONFLICT', 'The installed preset changed');
+        const configured = nodeConfig ?? current.receipt?.nodeConfig ?? Object.fromEntries(Object.entries(current.activation?.modules ?? {}).filter(([, entry]) => entry.config !== undefined).map(([id, entry]) => [id, entry.config]));
+        const selected = await prepareNodeBundleSnapshot(prepared.bundles.filter(bundle => prepared.preset.packages[bundle.manifest.id].runtimes?.includes('node')), 'native-host', this.mearlApiVersion, resolvePresetModuleConfig(mergePresetDefaults(prepared.preset.defaults, acceptedOverrides ?? current.receipt?.overrides ?? {}), configured));
+        const previousManaged = new Set(current.receipt?.managedModules ?? []);
+        const unmanaged = Object.fromEntries(Object.entries(current.activation?.modules ?? {}).filter(([id]) => !previousManaged.has(id)));
+        for (const entry of Object.values(unmanaged)) {
+            const bytes = readBounded(join(this.directory, 'objects', `${entry.sha256}.cjs`), entry.byteLength);
+            if (bytes.byteLength !== entry.byteLength || digest(bytes) !== entry.sha256)
+                throw new BundleError('BUNDLE_INTEGRITY', 'An independent Node module is corrupt');
+        }
+        if (Object.keys(selected.snapshot.modules).some(id => Object.hasOwn(unmanaged, id)))
+            throw new BundleError('BUNDLE_CONFLICT', 'A preset module conflicts with an independently installed Node module');
+        const bindings = Object.fromEntries(Object.entries(current.activation?.bindings ?? {}).filter(([, entry]) => Object.hasOwn(unmanaged, entry.module)));
+        if (Object.keys(selected.snapshot.bindings).some(hook => Object.hasOwn(bindings, hook)))
+            throw new BundleError('BUNDLE_CONFLICT', 'A preset hook conflicts with an independently installed Node module');
+        const snapshot = await prepareNodeCapabilitySnapshot({ schemaVersion: 1, modules: { ...unmanaged, ...selected.snapshot.modules }, bindings: { ...bindings, ...selected.snapshot.bindings } });
+        const data = {
+            schemaVersion: 1, snapshot: prepared.snapshot,
+            bundles: prepared.bundles.map(({ source, revision, manifest }) => ({ source, revision, manifest })),
+            browserRevision: prepared.browser.snapshot.revision, nodeRevision: snapshot.revision,
+            managedModules: Object.keys(selected.snapshot.modules), overrides: acceptedOverrides ?? current.receipt?.overrides ?? {},
+            nodeSyncRequired: Boolean(current.receipt?.nodeSyncRequired || current.receipt?.managedModules.length || Object.values(prepared.preset.packages).some(entry => entry.enabled !== false && entry.runtimes?.includes('node'))),
+            browserSyncRequired: Boolean(current.receipt?.browserSyncRequired || presetRequiresBrowser(prepared.preset)),
+            nodeConfig: configured,
+        };
+        const receipt = { ...data, revision: digest(JSON.stringify(data)) };
+        const receiptBytes = JSON.stringify(receipt);
+        if (Buffer.byteLength(receiptBytes) > MAX_RECEIPT_BYTES)
+            throw new BundleError('BUNDLE_QUOTA', 'Preset installation receipt exceeds 16 MiB');
+        const activation = { ...snapshot, installationRevision: receipt.revision };
+        await options.confirm?.();
+        withRecordLock(this.pointer, () => {
+            this.assertCurrent(current.rawHash);
+            options.signal?.throwIfAborted();
+            for (const child of ['blobs', 'objects', 'installations'])
+                mkdirSync(join(this.directory, child), { recursive: true, mode: 0o700 });
+            for (const bundle of prepared.bundles)
+                for (const [name, entry] of Object.entries(bundle.manifest.resources)) {
+                    atomicWrite(join(this.directory, 'blobs', `${entry.sha256}.bin`), bundle.resources[name]);
+                }
+            for (const entry of Object.values(selected.snapshot.modules)) {
+                const destination = join(this.directory, 'objects', `${entry.sha256}.cjs`);
+                const temporary = `${destination}.${randomUUID()}.tmp`;
+                try {
+                    linkSync(join(this.directory, 'blobs', `${entry.sha256}.bin`), temporary);
+                    renameSync(temporary, destination);
+                }
+                finally {
+                    rmSync(temporary, { force: true });
+                }
+            }
+            atomicWrite(join(this.directory, 'installations', `${receipt.revision}.json`), receiptBytes);
+            if (current.receipt?.revision !== receipt.revision)
+                atomicWrite(join(this.directory, 'rollback.json'), JSON.stringify({ candidate: receipt.revision, previous: current.activation ?? null }));
+            atomicWrite(this.pointer, JSON.stringify(activation));
+        });
+        return receipt;
+    }
+    async rollback(expectedRevision) {
+        const current = await this.current({ verifyResources: false });
+        if (current.activation?.installationRevision !== expectedRevision)
+            throw new BundleError('BUNDLE_CONFLICT', 'A newer preset installation cannot be rolled back');
+        const record = JSON.parse(readBounded(join(this.directory, 'rollback.json'), POINTER_BYTES + 256).toString('utf8'));
+        if (record.candidate !== expectedRevision)
+            throw new BundleError('BUNDLE_CONFLICT', 'The preset rollback record has changed');
+        const previous = record.previous === null ? undefined : await verifyNodeCapabilityActivation(record.previous);
+        withRecordLock(this.pointer, () => {
+            this.assertCurrent(current.rawHash);
+            if (previous)
+                atomicWrite(this.pointer, JSON.stringify(previous));
+            else
+                rmSync(this.pointer, { force: true });
+            rmSync(join(this.directory, 'rollback.json'), { force: true });
+            this.collectLocked(previous);
+        });
+    }
+    async collectGarbage() {
+        const current = await this.current({ verifyResources: false });
+        const raw = optionalFile(join(this.directory, 'rollback.json'), POINTER_BYTES + 256);
+        const record = raw && JSON.parse(raw.toString('utf8'));
+        const previous = record?.candidate === current.activation?.installationRevision && record.previous !== null ? await verifyNodeCapabilityActivation(record.previous) : undefined;
+        withRecordLock(this.pointer, () => {
+            this.assertCurrent(current.rawHash);
+            for (const child of ['blobs', 'objects', 'installations'])
+                mkdirSync(join(this.directory, child), { recursive: true, mode: 0o700 });
+            this.collectLocked(current.activation, previous);
+        });
+    }
+    collectLocked(active, previous) {
+        const receipts = new Set([active?.installationRevision, previous?.installationRevision].filter((value) => Boolean(value)));
+        const blobs = new Set();
+        const modules = new Set([active, previous].flatMap(selection => Object.values(selection?.modules ?? {}).map(entry => entry.sha256)));
+        for (const id of receipts) {
+            const record = JSON.parse(readBounded(join(this.directory, 'installations', `${id}.json`), MAX_RECEIPT_BYTES).toString('utf8'));
+            for (const bundle of record.bundles)
+                for (const entry of Object.values(bundle.manifest.resources))
+                    blobs.add(entry.sha256);
+        }
+        for (const [directory, extension, retained] of [['blobs', '.bin', blobs], ['objects', '.cjs', modules], ['installations', '.json', receipts]]) {
+            for (const name of readdirSync(join(this.directory, directory))) {
+                const id = name.slice(0, -extension.length);
+                if (name.endsWith(extension) && hashPattern.test(id) && !retained.has(id))
+                    rmSync(join(this.directory, directory, name), { force: true });
+            }
+        }
+    }
+}
+export function presetSelectionRevision(state) { return revision(state); }

package/dist/presetUpgrade.d.ts

@@ -0,0 +1,13 @@
+import { type InstallationConfig } from '@mearl/preset/installation';
+import { PresetInstaller, type StagedPresetInstallation } from './preset.js';
+import { type DetectedGlobalPackage } from './packageManager.js';
+export declare const MEARL_INSTALLATION_CONFIG_URL = "https://f-loat.github.io/mearl/installation.json";
+/** Reuse the installation receipt as the retry marker; organization defaults come from deployment data. */
+export declare function prepareSetupPreset(options: {
+    source?: string;
+    installed?: Array<Pick<DetectedGlobalPackage, 'packageName' | 'packageRoot'>>;
+    env?: NodeJS.ProcessEnv;
+}, dependencies?: {
+    installer?: PresetInstaller;
+    configuration?: () => Promise<InstallationConfig>;
+}): Promise<StagedPresetInstallation | undefined>;

package/dist/presetUpgrade.js

@@ -0,0 +1,42 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadInstallationConfig } from '@mearl/preset/installation';
+import { PresetInstaller } from './preset.js';
+import { detectGlobalPackage } from './packageManager.js';
+import { detectMearlProfiles } from './profiles.js';
+export const MEARL_INSTALLATION_CONFIG_URL = 'https://f-loat.github.io/mearl/installation.json';
+function isLegacyPackage(installation) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(installation.packageRoot, 'package.json'), 'utf8'));
+        return manifest.name === installation.packageName && typeof manifest.version === 'string' && /^[0-2]\.\d+\.\d+(?:[-+][\w.-]+)?$/.test(manifest.version);
+    }
+    catch {
+        return false;
+    }
+}
+/** Reuse the installation receipt as the retry marker; organization defaults come from deployment data. */
+export async function prepareSetupPreset(options, dependencies = {}) {
+    const env = options.env ?? process.env;
+    const installer = dependencies.installer ?? new PresetInstaller({ directory: env.MEARL_CAPABILITY_DIR });
+    if (options.source)
+        return installer.stage(options.source);
+    const current = await installer.store.current();
+    if (current.receipt)
+        return { revision: current.receipt.revision, activate: () => installer.resume(current.receipt.revision) };
+    if (current.activation)
+        return;
+    const client = options.installed === undefined ? detectGlobalPackage('@mearl/client', ['mearl'], { env }) : null;
+    const installed = options.installed ?? [...detectMearlProfiles({ env }).values(), ...(client ? [client] : [])];
+    if (!installed.some(isLegacyPackage))
+        return;
+    const configuration = dependencies.configuration ?? (() => {
+        const url = new URL(env.MEARL_INSTALLATION_CONFIG_URL || MEARL_INSTALLATION_CONFIG_URL);
+        if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)))
+            throw new Error('Installation configuration requires HTTPS or loopback HTTP');
+        return loadInstallationConfig(url, url.origin, AbortSignal.timeout(5_000));
+    });
+    const config = await configuration();
+    if (!config.legacyPreset)
+        throw new Error('Legacy upgrade preset is unavailable. Retry when the installation catalog is available, or select a preset with --preset.');
+    return installer.stage(config.presets[config.legacyPreset].source, { expectedRevision: null, expectedId: config.legacyPreset });
+}

package/dist/provider.d.ts

@@ -20,6 +20,8 @@ export interface ProviderSetupResult {
     manifest: InstalledProviderManifest;
     manager: PackageManagerInstallation['manager'];
 }
+/** A registry record alone does not prove that the package still exists. */
+export declare function inspectProviderPackage(manifest: InstalledProviderManifest): boolean;
 export declare function parseProviderPackageSpec(value: string): ProviderPackageSpec;
 export declare function installProviderPackage(packageSpec: string, dependencies?: ProviderSetupDependencies): Promise<ProviderSetupResult>;
 export declare function updateProviderPackage(selector: string, dependencies?: ProviderSetupDependencies): Promise<ProviderSetupResult>;

package/dist/provider.js

@@ -1,9 +1,28 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { listInstalledProviders, registerProviderPackage, stopProvider, readLiveProvider, readProviderStart, uninstallProvider, } from '@mearl/provider/host';
+import { listInstalledProviders, validateInstalledProviderManifest, registerProviderPackage, stopProvider, readLiveProvider, readProviderStart, uninstallProvider, } from '@mearl/provider/host';
 import { buildGlobalPackageCommand, resolveInvokingPackageManager, resolvePackageManagerInstallation, } from './packageManager.js';
 import { packageRegistryEnvironment } from './npmRegistry.js';
 import { isProcessOwnerAlive, processIdentity, prependCommandPath, runCommand, } from '@mearl/daemon-core';
+/** A registry record alone does not prove that the package still exists. */
+export function inspectProviderPackage(manifest) {
+    if (validateInstalledProviderManifest(manifest))
+        return false;
+    try {
+        const file = join(manifest.packageRoot, 'package.json');
+        const stat = statSync(file);
+        if (!stat.isFile() || stat.size > 1024 * 1024)
+            return false;
+        const metadata = JSON.parse(readFileSync(file, 'utf8'));
+        const provider = metadata.mearl?.provider;
+        return metadata.name === manifest.packageName && metadata.version === manifest.version &&
+            provider?.providerId === manifest.providerId && provider.protocolVersion === manifest.protocolVersion &&
+            typeof provider.entry === 'string' && resolve(manifest.packageRoot, provider.entry) === manifest.entryPath;
+    }
+    catch {
+        return false;
+    }
+}
 async function stopProviderBeforePackageChange(providerId) {
     if (readProviderStart(providerId))
         throw new Error(`Provider ${providerId} is still starting`);
@@ -96,6 +115,9 @@ export async function installProviderPackage(packageSpec, dependencies = {}) {
     const env = process.env;
     const runner = dependencies.runCommand ?? runCommand;
     const installation = providerManager(env, dependencies);
+    const previous = (dependencies.listProviders ?? listInstalledProviders)().filter(provider => provider.packageName === packageName);
+    for (const provider of previous)
+        await (dependencies.stopProvider ?? stopProviderBeforePackageChange)(provider.providerId);
     await runPackageCommand(installation, 'install', packageName, target, runner, env);
     const packageRoot = await (dependencies.resolvePackageRoot ?? resolveGlobalProviderPackageRoot)(installation, packageName, runner, env);
     if (!(dependencies.existsSync ?? existsSync)(join(packageRoot, 'package.json'))) {

package/dist/runtimeCleanup.js

@@ -1,4 +1,4 @@
-import { readdirSync, rmSync } from 'node:fs';
+import { readdirSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { cleanupPluginRuntime, pluginDirectory } from '@mearl/client/plugin';
@@ -18,13 +18,6 @@ export async function cleanupUninstalledRuntime() {
         }))
             throw new Error('Providers still use runtime caches; caches were retained');
     }
-    for (const directory of [
-        'authx-sdk',
-        'design-overlay/objects',
-        'design-overlay/uploads',
-        'design-overlay/pages',
-    ])
-        rmSync(join(root, directory), { recursive: true, force: true });
     pruneOrphanLogs(join(root, 'managed-browsers'), 0);
     pruneOrphanLogs(join(root, 'providers/logs'), 0);
     let entries;

package/dist/setupVersion.d.ts

@@ -0,0 +1,2 @@
+export declare const SETUP_VERSION: string;
+export declare const SETUP_COMMAND: string;

package/dist/setupVersion.js

@@ -0,0 +1,4 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+export const SETUP_VERSION = require('../package.json').version;
+export const SETUP_COMMAND = `npx @mearl/setup${SETUP_VERSION.includes('-beta.') ? '@' + SETUP_VERSION : ''}`;

package/dist/skillSources.d.ts

@@ -0,0 +1,43 @@
+import { type CommandRunner } from '@mearl/daemon-core';
+export type SkillSourceScope = 'global' | 'project';
+export interface TrackedSkillSource {
+    name: string;
+    source: string;
+    scope: SkillSourceScope;
+    ref?: string;
+    skillPath?: string;
+    sourceType?: string;
+    expectedHash?: string;
+    hashKind: 'git-tree' | 'folder';
+}
+interface SourceOptions {
+    env?: NodeJS.ProcessEnv;
+    homeDirectory?: string;
+}
+export declare function readTrackedSkillSources(scope: SkillSourceScope, cwd?: string, options?: SourceOptions): TrackedSkillSource[];
+/** Custom source kinds require their installed backend, even if they use owner/repo syntax. */
+export declare function isPublicSkillSource(source: TrackedSkillSource): boolean;
+/** Compare the manager's existing source receipt; no network access or second lockfile. */
+export declare function matchesTrackedSkillSource(requested: string, tracked: TrackedSkillSource, normalize?: (source: string, sourceType?: string) => string): boolean;
+/** Matches the public Skills folder hash without writing to the installed Skill. */
+export declare function hashSkillDirectory(directory: string, ignoreRuntimeFiles?: boolean): Promise<string>;
+/** Checks source content in a temporary checkout; never invokes the mutating Skills `check` alias. */
+export declare function checkTrackedSkillUpdates(options?: SourceOptions & {
+    cwd?: string;
+    runCommand?: CommandRunner;
+}): Promise<Array<{
+    name: string;
+    source: string;
+    scope: SkillSourceScope;
+}>>;
+export interface SkillInstallationStatus {
+    state: 'ready' | 'missing' | 'version' | 'registration' | 'conflict';
+    reason?: string;
+}
+/** CLI and Agent readiness use the same source, manifest and registration evidence. */
+export declare function inspectGlobalSkill(source: string, name: string, version?: string, options?: {
+    readSources?: typeof readTrackedSkillSources;
+    externalManager?: boolean;
+    normalizeSource?: (source: string, sourceType?: string) => string;
+}): SkillInstallationStatus;
+export {};