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

package/dist/presetStore.js

@@ -1,252 +1 @@
-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); }
+export { PresetInstallationStore, presetSelectionRevision } from '@mearl/daemon-core/installation';

package/dist/setupPreset.d.ts

@@ -0,0 +1,9 @@
+import { PresetInstaller, type StagedPresetInstallation } from './preset.js';
+/** Preserve the accepted installation and resume its exact resources before Skill operations. */
+export declare function prepareSetupPreset(options: {
+    source?: string;
+    fallbackSource?: string;
+    env?: NodeJS.ProcessEnv;
+}, dependencies?: {
+    installer?: PresetInstaller;
+}): Promise<StagedPresetInstallation | undefined>;

package/dist/setupPreset.js

@@ -0,0 +1,14 @@
+import { PresetInstaller } from './preset.js';
+/** Preserve the accepted installation and resume its exact resources before Skill operations. */
+export async function prepareSetupPreset(options, dependencies = {}) {
+    const installer = dependencies.installer ?? new PresetInstaller({ directory: (options.env ?? process.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;
+    if (options.fallbackSource)
+        return installer.stage(options.fallbackSource);
+}

package/dist/setupVersion.js

@@ -1,4 +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 : ''}`;
+export const SETUP_COMMAND = `npx @mearl/setup${SETUP_VERSION.includes('-beta.') ? '@beta' : ''}`;

package/dist/skillSourceReceipts.d.ts

@@ -0,0 +1,25 @@
+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';
+}
+export 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;
+export declare function gitSource(source: string, ref?: string): {
+    repository: string;
+    ref?: string;
+    subdirectory?: string;
+};
+/** Compare the manager's existing source receipt; no network access or second lockfile. */
+export declare function matchesTrackedSkillSource(requested: string, tracked: TrackedSkillSource, normalize?: (source: string, sourceType?: string) => string): boolean;

package/dist/skillSourceReceipts.js

@@ -0,0 +1,94 @@
+import { readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+function lockFile(scope, cwd, options) {
+    const env = options.env ?? process.env;
+    return scope === 'project' ? join(cwd, 'skills-lock.json') : env.XDG_STATE_HOME ? join(env.XDG_STATE_HOME, 'skills', '.skill-lock.json') : join(options.homeDirectory ?? homedir(), '.agents', '.skill-lock.json');
+}
+export function readTrackedSkillSources(scope, cwd, options = {}) {
+    const file = lockFile(scope, cwd, options);
+    let text;
+    try {
+        if (statSync(file).size > 4 * 1024 * 1024)
+            throw new Error('Skill source lock exceeds 4 MiB');
+        text = readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const lock = JSON.parse(text);
+    if (!lock || !lock.skills || typeof lock.skills !== 'object' || Array.isArray(lock.skills))
+        throw new Error('Invalid Skills source lock');
+    return Object.entries(lock.skills).flatMap(([name, entry]) => {
+        if (!entry || typeof entry !== 'object' || entry.sourceType === 'node_modules')
+            return [];
+        if (!name || name === '.' || name === '..' || /[\\/\0\r\n]/.test(name))
+            throw new Error('Invalid tracked Skill name');
+        const source = typeof entry.sourceUrl === 'string' ? entry.sourceUrl : entry.source;
+        if (typeof source !== 'string' || !source.trim())
+            return [];
+        if (source.length > 4096 || /[\0\r\n]/.test(source))
+            throw new Error('Invalid tracked Skill source');
+        const expectedHash = scope === 'global' ? entry.skillFolderHash : entry.computedHash;
+        return [{ name, source, scope, ...(typeof entry.sourceType === 'string' ? { sourceType: entry.sourceType } : {}), ...(typeof entry.ref === 'string' ? { ref: entry.ref } : {}), ...(typeof entry.skillPath === 'string' ? { skillPath: entry.skillPath } : {}), ...(typeof expectedHash === 'string' && expectedHash ? { expectedHash } : {}), hashKind: scope === 'global' && typeof expectedHash === 'string' && /^[a-f0-9]{40}$/.test(expectedHash) ? 'git-tree' : 'folder' }];
+    });
+}
+/** Custom source kinds require their installed backend, even if they use owner/repo syntax. */
+export function isPublicSkillSource(source) {
+    return source.sourceType === undefined || ['github', 'gitlab', 'git', 'local', 'well-known'].includes(source.sourceType);
+}
+export function gitSource(source, ref) {
+    if (/^[\w.-]+\/[\w.-]+$/.test(source))
+        return { repository: `https://github.com/${source}.git`, ...(ref ? { ref } : {}) };
+    if (/^[\w.-]+@[\w.-]+:[^\s]+$/.test(source))
+        return { repository: source, ...(ref ? { ref } : {}) };
+    const url = new URL(source);
+    if (!['https:', 'http:', 'ssh:', 'git:', 'file:'].includes(url.protocol) || url.password || (url.username && url.protocol !== 'ssh:') || url.search || url.hash)
+        throw new Error('Skill source is not a supported Git repository');
+    if (url.hostname === 'github.com' && !url.port) {
+        const parts = url.pathname.split('/').filter(Boolean);
+        if (parts.length >= 2)
+            return { repository: `https://github.com/${parts[0]}/${parts[1].replace(/\.git$/, '')}.git`, ...(ref || (['tree', 'blob'].includes(parts[2]) && parts[3]) ? { ref: ref || decodeURIComponent(parts[3]) } : {}), ...(['tree', 'blob'].includes(parts[2]) && parts.length > 4 ? { subdirectory: decodeURIComponent(parts.slice(4).join('/')).replace(/\/SKILL\.md$/, '') } : {}) };
+    }
+    return { repository: url.href, ...(ref ? { ref } : {}) };
+}
+/** Compare the manager's existing source receipt; no network access or second lockfile. */
+export function matchesTrackedSkillSource(requested, tracked, normalize = source => source) {
+    const location = (source, ref, sourceType) => {
+        const value = normalize(source, sourceType);
+        if (typeof value !== 'string' || !value || value.length > 8192 || /[\0\r\n]/.test(value))
+            throw new Error('Invalid normalized Skill source');
+        const hash = value.indexOf('#');
+        const fragment = hash < 0 ? undefined : value.slice(hash + 1);
+        const plain = hash < 0 ? value : value.slice(0, hash);
+        const parsed = isAbsolute(plain) ? { repository: plain, ref: ref ?? fragment } : gitSource(plain, ref ?? fragment);
+        let repository = parsed.repository;
+        if (repository.startsWith('file:'))
+            repository = fileURLToPath(repository);
+        if (isAbsolute(repository))
+            repository = resolve(repository);
+        else {
+            const ssh = repository.match(/^[\w.-]+@([\w.-]+):(.+)$/);
+            const url = new URL(ssh ? `ssh://${ssh[1]}/${ssh[2]}` : repository);
+            // Authentication transport is independent of the repository's identity.
+            repository = `${url.hostname.toLowerCase()}${url.port ? ':' + url.port : ''}/${url.pathname.replace(/^\/+|\/+$/g, '').replace(/\.git$/, '')}`;
+        }
+        return { ...parsed, repository, ref: parsed.ref || undefined };
+    };
+    try {
+        const expected = location(requested);
+        const actual = location(tracked.source, tracked.ref, tracked.sourceType);
+        if (expected.repository !== actual.repository || expected.ref !== actual.ref)
+            return false;
+        if (!expected.subdirectory)
+            return true;
+        const path = (tracked.skillPath ?? actual.subdirectory ?? '').replace(/(?:^|\/)SKILL\.md$/, '').replace(/\/+$/, '');
+        return path === expected.subdirectory || path.startsWith(expected.subdirectory + '/');
+    }
+    catch {
+        return normalize(requested) === normalize(tracked.source, tracked.sourceType) && !tracked.ref;
+    }
+}

package/dist/skillSources.d.ts

@@ -1,24 +1,7 @@
 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;
+import { readTrackedSkillSources, type SourceOptions, type SkillSourceScope, type TrackedSkillSource } from './skillSourceReceipts.js';
+export { isPublicSkillSource, matchesTrackedSkillSource, readTrackedSkillSources } from './skillSourceReceipts.js';
+export type { SkillSourceScope, TrackedSkillSource } from './skillSourceReceipts.js';
 /** Matches the public Skills folder hash without writing to the installed Skill. */
 export declare function hashSkillDirectory(directory: string, ignoreRuntimeFiles?: boolean): Promise<string>;
 /** Checks source content in a temporary checkout; never invokes the mutating Skills `check` alias. */
@@ -31,16 +14,18 @@ export declare function checkTrackedSkillUpdates(options?: SourceOptions & {
     scope: SkillSourceScope;
 }>>;
 export interface SkillInstallationStatus {
-    state: 'ready' | 'missing' | 'version' | 'registration' | 'conflict';
+    state: 'ready' | 'missing' | 'version' | 'registration' | 'migration' | 'conflict';
     reason?: string;
 }
 /** Developer links keep their Git checkout as the source receipt without changing a manager's lock. */
 export declare function readLinkedSkillSource(directory: string, name: string): TrackedSkillSource | undefined;
+/** Keep the user's disabled state when an installer replaces the Skill directory. */
+export declare function preserveSkillDisabled<T>(directory: string, operation: () => Promise<T>): Promise<T>;
 /** CLI and Agent readiness use the same source, manifest and registration evidence. */
 export declare function inspectGlobalSkill(source: string, name: string, version?: string, options?: {
     homeDirectory?: string;
     readSources?: typeof readTrackedSkillSources;
     externalManager?: boolean;
+    migrateFrom?: readonly string[];
     normalizeSource?: (source: string, sourceType?: string) => string;
 }): SkillInstallationStatus;
-export {};

package/dist/skillSources.js

@@ -1,104 +1,15 @@
 import { createHash } from 'node:crypto';
 import { mkdtemp, readFile, readdir, realpath, rm, stat } from 'node:fs/promises';
-import { readFileSync, statSync, lstatSync, realpathSync } from 'node:fs';
+import { lstatSync, realpathSync, renameSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { homedir, tmpdir } from 'node:os';
-import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { runCommand } from '@mearl/daemon-core';
 import { satisfies, valid } from 'semver';
-import { DISABLED_SKILL_MANIFEST, findPluginDirectoryEntry, findPluginRegistration, listPluginNames, OFFICIAL_PLUGIN_MANAGER, pluginRegistrationNeedsRefresh, readInstalledSkillMetadata } from '@mearl/client/plugin';
+import { DISABLED_SKILL_MANIFEST, getSkillEnabled, findPluginDirectoryEntry, findPluginRegistration, listPluginNames, OFFICIAL_PLUGIN_MANAGER, pluginRegistrationNeedsRefresh, readInstalledSkillMetadata } from '@mearl/client/plugin';
 import { existsSync } from 'node:fs';
-function lockFile(scope, cwd, options) {
-    const env = options.env ?? process.env;
-    return scope === 'project' ? join(cwd, 'skills-lock.json') : env.XDG_STATE_HOME ? join(env.XDG_STATE_HOME, 'skills', '.skill-lock.json') : join(options.homeDirectory ?? homedir(), '.agents', '.skill-lock.json');
-}
-export function readTrackedSkillSources(scope, cwd, options = {}) {
-    const file = lockFile(scope, cwd, options);
-    let text;
-    try {
-        if (statSync(file).size > 4 * 1024 * 1024)
-            throw new Error('Skill source lock exceeds 4 MiB');
-        text = readFileSync(file, 'utf8');
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return [];
-        throw error;
-    }
-    const lock = JSON.parse(text);
-    if (!lock || !lock.skills || typeof lock.skills !== 'object' || Array.isArray(lock.skills))
-        throw new Error('Invalid Skills source lock');
-    return Object.entries(lock.skills).flatMap(([name, entry]) => {
-        if (!entry || typeof entry !== 'object' || entry.sourceType === 'node_modules')
-            return [];
-        if (!name || name === '.' || name === '..' || /[\\/\0\r\n]/.test(name))
-            throw new Error('Invalid tracked Skill name');
-        const source = typeof entry.sourceUrl === 'string' ? entry.sourceUrl : entry.source;
-        if (typeof source !== 'string' || !source.trim())
-            return [];
-        if (source.length > 4096 || /[\0\r\n]/.test(source))
-            throw new Error('Invalid tracked Skill source');
-        const expectedHash = scope === 'global' ? entry.skillFolderHash : entry.computedHash;
-        return [{ name, source, scope, ...(typeof entry.sourceType === 'string' ? { sourceType: entry.sourceType } : {}), ...(typeof entry.ref === 'string' ? { ref: entry.ref } : {}), ...(typeof entry.skillPath === 'string' ? { skillPath: entry.skillPath } : {}), ...(typeof expectedHash === 'string' && expectedHash ? { expectedHash } : {}), hashKind: scope === 'global' && typeof expectedHash === 'string' && /^[a-f0-9]{40}$/.test(expectedHash) ? 'git-tree' : 'folder' }];
-    });
-}
-/** Custom source kinds require their installed backend, even if they use owner/repo syntax. */
-export function isPublicSkillSource(source) {
-    return source.sourceType === undefined || ['github', 'gitlab', 'git', 'local', 'well-known'].includes(source.sourceType);
-}
-function gitSource(source, ref) {
-    if (/^[\w.-]+\/[\w.-]+$/.test(source))
-        return { repository: `https://github.com/${source}.git`, ...(ref ? { ref } : {}) };
-    if (/^[\w.-]+@[\w.-]+:[^\s]+$/.test(source))
-        return { repository: source, ...(ref ? { ref } : {}) };
-    const url = new URL(source);
-    if (!['https:', 'http:', 'ssh:', 'git:', 'file:'].includes(url.protocol) || url.password || (url.username && url.protocol !== 'ssh:') || url.search || url.hash)
-        throw new Error('Skill source is not a supported Git repository');
-    if (url.hostname === 'github.com' && !url.port) {
-        const parts = url.pathname.split('/').filter(Boolean);
-        if (parts.length >= 2)
-            return { repository: `https://github.com/${parts[0]}/${parts[1].replace(/\.git$/, '')}.git`, ...(ref || (['tree', 'blob'].includes(parts[2]) && parts[3]) ? { ref: ref || decodeURIComponent(parts[3]) } : {}), ...(['tree', 'blob'].includes(parts[2]) && parts.length > 4 ? { subdirectory: decodeURIComponent(parts.slice(4).join('/')).replace(/\/SKILL\.md$/, '') } : {}) };
-    }
-    return { repository: url.href, ...(ref ? { ref } : {}) };
-}
-/** Compare the manager's existing source receipt; no network access or second lockfile. */
-export function matchesTrackedSkillSource(requested, tracked, normalize = source => source) {
-    const location = (source, ref, sourceType) => {
-        const value = normalize(source, sourceType);
-        if (typeof value !== 'string' || !value || value.length > 8192 || /[\0\r\n]/.test(value))
-            throw new Error('Invalid normalized Skill source');
-        const hash = value.indexOf('#');
-        const fragment = hash < 0 ? undefined : value.slice(hash + 1);
-        const plain = hash < 0 ? value : value.slice(0, hash);
-        const parsed = isAbsolute(plain) ? { repository: plain, ref: ref ?? fragment } : gitSource(plain, ref ?? fragment);
-        let repository = parsed.repository;
-        if (repository.startsWith('file:'))
-            repository = fileURLToPath(repository);
-        if (isAbsolute(repository))
-            repository = resolve(repository);
-        else {
-            const ssh = repository.match(/^[\w.-]+@([\w.-]+):(.+)$/);
-            const url = new URL(ssh ? `ssh://${ssh[1]}/${ssh[2]}` : repository);
-            // Authentication transport is independent of the repository's identity.
-            repository = `${url.hostname.toLowerCase()}${url.port ? ':' + url.port : ''}/${url.pathname.replace(/^\/+|\/+$/g, '').replace(/\.git$/, '')}`;
-        }
-        return { ...parsed, repository, ref: parsed.ref || undefined };
-    };
-    try {
-        const expected = location(requested);
-        const actual = location(tracked.source, tracked.ref, tracked.sourceType);
-        if (expected.repository !== actual.repository || expected.ref !== actual.ref)
-            return false;
-        if (!expected.subdirectory)
-            return true;
-        const path = (tracked.skillPath ?? actual.subdirectory ?? '').replace(/(?:^|\/)SKILL\.md$/, '').replace(/\/+$/, '');
-        return path === expected.subdirectory || path.startsWith(expected.subdirectory + '/');
-    }
-    catch {
-        return normalize(requested) === normalize(tracked.source, tracked.sourceType) && !tracked.ref;
-    }
-}
+import { gitSource, isPublicSkillSource, matchesTrackedSkillSource, readTrackedSkillSources } from './skillSourceReceipts.js';
+export { isPublicSkillSource, matchesTrackedSkillSource, readTrackedSkillSources } from './skillSourceReceipts.js';
 function skillName(text) {
     return text.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1].match(/^name:\s*["']?([^"'\r\n]+?)["']?\s*$/m)?.[1]?.trim();
 }
@@ -237,6 +148,35 @@ export function readLinkedSkillSource(directory, name) {
         return undefined;
     }
 }
+/** Keep the user's disabled state when an installer replaces the Skill directory. */
+export async function preserveSkillDisabled(directory, operation) {
+    const disabled = getSkillEnabled(directory) === false;
+    try {
+        return await operation();
+    }
+    finally {
+        if (disabled && existsSync(join(directory, 'SKILL.md')))
+            renameSync(join(directory, 'SKILL.md'), join(directory, DISABLED_SKILL_MANIFEST));
+    }
+}
+function canonicalPath(path) {
+    const absolute = resolve(path);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        const parent = dirname(absolute);
+        return parent === absolute ? absolute : join(canonicalPath(parent), basename(absolute));
+    }
+}
+function hasOnlySetupRegistrations(directory) {
+    const contains = (root, entry) => {
+        const path = relative(root, entry);
+        return path !== '' && path !== '..' && !path.startsWith('..' + sep) && !isAbsolute(path);
+    };
+    const registrations = listPluginNames().flatMap(name => findPluginRegistration(name) ?? []).filter(registration => contains(resolve(directory), resolve(registration.entry)) || contains(canonicalPath(directory), canonicalPath(registration.entry)));
+    return registrations.length > 0 && registrations.every(registration => registration.managedBy === OFFICIAL_PLUGIN_MANAGER);
+}
 /** CLI and Agent readiness use the same source, manifest and registration evidence. */
 export function inspectGlobalSkill(source, name, version, options = {}) {
     if (!source.trim() || !name || name === '.' || name === '..' || /[\\/\0\r\n]/.test(name))
@@ -244,10 +184,17 @@ export function inspectGlobalSkill(source, name, version, options = {}) {
     const directory = join(options.homeDirectory ?? homedir(), '.agents', 'skills', name);
     if (existsSync(join(directory, 'SKILL.md')) && existsSync(join(directory, DISABLED_SKILL_MANIFEST)))
         return { state: 'conflict', reason: 'SKILL_MANIFEST_CONFLICT' };
-    const tracked = (options.readSources ?? readTrackedSkillSources)('global', undefined, { homeDirectory: options.homeDirectory }).find(entry => entry.name === name)
+    const receipt = (options.readSources ?? readTrackedSkillSources)('global', undefined, { homeDirectory: options.homeDirectory }).find(entry => entry.name === name);
+    const tracked = receipt
         ?? (!/(?:#|\/(?:tree|blob)\/)/.test(source) ? readLinkedSkillSource(directory, name) : undefined);
-    if (tracked && ((!options.externalManager && !isPublicSkillSource(tracked)) || !matchesTrackedSkillSource(source, tracked, options.normalizeSource)))
+    if (tracked && ((!options.externalManager && !isPublicSkillSource(tracked)) || !matchesTrackedSkillSource(source, tracked, options.normalizeSource))) {
+        const metadata = readInstalledSkillMetadata(directory);
+        if (receipt && (options.externalManager || isPublicSkillSource(receipt)) && metadata?.name === name &&
+            options.migrateFrom?.some(previous => matchesTrackedSkillSource(previous, receipt, options.normalizeSource)) && hasOnlySetupRegistrations(directory)) {
+            return { state: 'migration', reason: 'SKILL_SOURCE_MIGRATION_REQUIRED' };
+        }
         return { state: 'conflict', reason: 'SKILL_SOURCE_CONFLICT' };
+    }
     const metadata = readInstalledSkillMetadata(directory);
     if (!metadata)
         return { state: 'missing', reason: 'SKILL_NOT_INSTALLED' };