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

package/dist/skillSources.js

@@ -1,103 +1,15 @@
 import { createHash } from 'node:crypto';
 import { mkdtemp, readFile, readdir, realpath, rm, stat } from 'node:fs/promises';
-import { readFileSync, statSync } 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();
 }
@@ -209,16 +121,80 @@ export async function checkTrackedSkillUpdates(options = {}) {
         await rm(temporary, { recursive: true, force: true });
     }
 }
+/** Developer links keep their Git checkout as the source receipt without changing a manager's lock. */
+export function readLinkedSkillSource(directory, name) {
+    try {
+        if (!lstatSync(directory).isSymbolicLink())
+            return undefined;
+        const actual = realpathSync(directory);
+        const git = (...args) => execFileSync('git', ['--no-optional-locks', '-c', 'core.fsmonitor=false', '-C', actual, ...args], {
+            encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2_000, maxBuffer: 16_384,
+        }).trim();
+        const root = git('rev-parse', '--show-toplevel');
+        const folder = relative(root, actual);
+        if (folder === '..' || folder.startsWith('..' + sep) || isAbsolute(folder))
+            return undefined;
+        const skillPath = (folder ? folder.split(sep).join('/') + '/' : '') + 'SKILL.md';
+        if (git('ls-files', '--full-name', '--error-unmatch', '--', 'SKILL.md') !== skillPath)
+            return undefined;
+        const source = git('config', '--get', 'remote.origin.url');
+        if (!source || source.length > 4096 || /[\0\r\n]/.test(source))
+            return undefined;
+        if (!isAbsolute(source))
+            gitSource(source);
+        return { name, source, scope: 'global', skillPath, sourceType: 'git', hashKind: 'folder' };
+    }
+    catch {
+        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))
         throw new Error('Invalid Skill identity');
-    const directory = join(homedir(), '.agents', 'skills', name);
+    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').find(entry => entry.name === name);
-    if (tracked && ((!options.externalManager && !isPublicSkillSource(tracked)) || !matchesTrackedSkillSource(source, tracked, options.normalizeSource)))
+    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))) {
+        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' };

package/dist/skills.js

@@ -4,11 +4,11 @@ import { homedir } from 'node:os';
 import { NodeCapabilityRegistry } from '@mearl/daemon-core/capabilities';
 import { inspectGlobalSkill, readTrackedSkillSources } from './skillSources.js';
 import { PresetInstallationStore } from './presetStore.js';
-import { findExecutable, isExecutable, prependCommandPath, prependNodePath, runCommand, } from '@mearl/daemon-core';
+import { findExecutable, isExecutable, npmExecEnvironment, prependCommandPath, prependNodePath, runCommand, } from '@mearl/daemon-core';
 export const SKILLS_CLI_PACKAGE = 'skills@1.5.0';
 export const MEARL_SKILL_SOURCE = SETUP_VERSION.includes('-beta.')
-    ? `https://github.com/F-loat/mearl/tree/v${SETUP_VERSION}`
-    : 'https://github.com/F-loat/mearl';
+    ? `https://github.com/mearlhq/mearl/tree/v${SETUP_VERSION}`
+    : 'https://github.com/mearlhq/mearl';
 const COMMAND_TIMEOUT_MS = 120_000;
 const ANSI_ESCAPE_PATTERN = new RegExp(String.raw `\u001B\[[0-?]*[ -/]*[@-~]`, 'g');
 export function stripAnsi(value) {
@@ -41,7 +41,7 @@ export function resolveSkillsInvocation(options = {}) {
     return {
         command: npx,
         argsPrefix: ['-y', SKILLS_CLI_PACKAGE],
-        env: prependNodePath(prependCommandPath(npx, env), processExecPath),
+        env: npmExecEnvironment(prependNodePath(prependCommandPath(npx, env), processExecPath)),
     };
 }
 /** Only the selected manager module is needed; browser and Provider factories stay in their hosts. */
@@ -59,9 +59,11 @@ export async function captureSkillsCli(options = {}) {
     const managedSkills = Object.fromEntries(Object.entries(current.preset?.skills ?? {}).filter(([, entry]) => entry.enabled !== false));
     const backend = registry.get('skills.manager')?.();
     if (backend !== undefined) {
+        if (backend?.readSources !== undefined && typeof backend.readSources !== 'function')
+            throw new Error('Invalid Skill source reader');
         if (!backend || typeof backend.id !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(backend.id) || typeof backend.cli !== 'function')
             throw new Error('The selected Skill manager requires a preset update for CLI operations');
-        return { id: backend.id, managedSkills, selection, inspectGlobal: (source, name, version) => inspectGlobalSkill(source, name, version, { externalManager: true, normalizeSource: backend.normalizeSource, readSources }), run: async (args, settings) => {
+        return { id: backend.id, managedSkills, selection, inspectGlobal: (source, name, version, inspection) => inspectGlobalSkill(source, name, version, { migrateFrom: inspection?.migrateFrom, externalManager: true, normalizeSource: backend.normalizeSource, readSources: backend.readSources ?? readSources }), run: async (args, settings) => {
                 const result = await backend.cli([...args], settings);
                 if (!result || !Number.isInteger(result.code) || typeof result.stdout !== 'string' || typeof result.stderr !== 'string')
                     throw new Error('Invalid Skill manager CLI result');
@@ -71,7 +73,7 @@ export async function captureSkillsCli(options = {}) {
     const invocation = resolveSkillsInvocation(options);
     if (!invocation)
         return undefined;
-    return { id: 'skills', managedSkills, selection, inspectGlobal: (source, name, version) => inspectGlobalSkill(source, name, version, { readSources }), run: (args, settings) => runner(invocation.command, [...invocation.argsPrefix, ...args], { ...settings, env: invocation.env }) };
+    return { id: 'skills', managedSkills, selection, inspectGlobal: (source, name, version, inspection) => inspectGlobalSkill(source, name, version, { migrateFrom: inspection?.migrateFrom, readSources }), run: (args, settings) => runner(invocation.command, [...invocation.argsPrefix, ...args], { ...settings, env: invocation.env }) };
 }
 export function parseInstalledSkills(output) {
     const value = JSON.parse(stripAnsi(output).trim());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "3.0.0-beta.0",
+  "version": "3.0.0-beta.10",
   "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",
@@ -45,6 +45,10 @@
     "./preset": {
       "types": "./dist/preset.d.ts",
       "import": "./dist/preset.js"
+    },
+    "./skill-source-receipts": {
+      "types": "./dist/skillSourceReceipts.d.ts",
+      "import": "./dist/skillSourceReceipts.js"
     }
   },
   "bin": {
@@ -64,27 +68,33 @@
   ],
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=20.18.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "commander": "^15.0.0",
-    "extract-zip": "^2.0.1",
+    "commander": "^14.0.3",
     "ws": "^8.18.3",
     "semver": "^7.8.5",
-    "@mearl/client": "3.0.0-beta.0",
-    "@mearl/provider": "3.0.0-beta.0",
-    "@mearl/daemon-core": "3.0.0-beta.0",
-    "@mearl/preset": "3.0.0-beta.0",
-    "@mearl/browser-core": "3.0.0-beta.0"
+    "adm-zip": "^0.6.1",
+    "@mearl/provider": "3.0.0-beta.10",
+    "@mearl/daemon-core": "3.0.0-beta.10",
+    "@mearl/client": "3.0.0-beta.10",
+    "@mearl/preset": "3.0.0-beta.10",
+    "@mearl/browser-core": "3.0.0-beta.10"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",
     "@types/ws": "^8.18.1",
     "typescript": "^5.8.3",
-    "@types/semver": "^7.7.1"
+    "@types/semver": "^7.7.1",
+    "@types/adm-zip": "^0.5.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mearlhq/mearl.git",
+    "directory": "packages/setup"
   },
   "scripts": {
     "build": "rm -rf dist/ && tsc && chmod +x dist/bin.js",

package/dist/presetUpgrade.d.ts

@@ -1,13 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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 });
-}