@mearl/setup 2.21.0 → 3.0.0-beta.0

package/dist/skillSources.js

@@ -0,0 +1,247 @@
+import { createHash } from 'node:crypto';
+import { mkdtemp, readFile, readdir, realpath, rm, stat } from 'node:fs/promises';
+import { readFileSync, statSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+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 { 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;
+    }
+}
+function skillName(text) {
+    return text.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1].match(/^name:\s*["']?([^"'\r\n]+?)["']?\s*$/m)?.[1]?.trim();
+}
+async function findSkillDirectory(root, name, skillPath) {
+    if (skillPath) {
+        const directory = resolve(root, skillPath.replace(/(?:^|\/)SKILL\.md$/, ''));
+        const resolvedRoot = await realpath(root);
+        const candidate = await realpath(directory);
+        if (candidate !== resolvedRoot && !candidate.startsWith(resolvedRoot + sep))
+            throw new Error('Skill source path escapes its repository');
+        if (skillName(await readFile(join(candidate, 'SKILL.md'), 'utf8')) === name)
+            return candidate;
+    }
+    const matches = [];
+    let scanned = 0;
+    const visit = async (directory, depth) => {
+        if (++scanned > 10_000 || depth > 32)
+            throw new Error('Skill source discovery exceeds its limit');
+        const entries = await readdir(directory, { withFileTypes: true });
+        const manifest = entries.find(entry => entry.name === 'SKILL.md' && entry.isFile());
+        if (manifest && skillName(await readFile(join(directory, 'SKILL.md'), 'utf8')) === name)
+            matches.push(directory);
+        for (const entry of entries)
+            if (entry.isDirectory() && !['.git', 'node_modules'].includes(entry.name))
+                await visit(join(directory, entry.name), depth + 1);
+    };
+    await visit(root, 0);
+    if (matches.length !== 1)
+        throw new Error(`Cannot uniquely locate Skill source: ${name}`);
+    return matches[0];
+}
+/** Matches the public Skills folder hash without writing to the installed Skill. */
+export async function hashSkillDirectory(directory, ignoreRuntimeFiles = false) {
+    const files = [];
+    let total = 0;
+    const visit = async (current) => {
+        for (const entry of await readdir(current, { withFileTypes: true })) {
+            if (['.git', 'node_modules'].includes(entry.name) || (ignoreRuntimeFiles && ['__pycache__', '.DS_Store'].includes(entry.name)))
+                continue;
+            const file = join(current, entry.name);
+            if (entry.isDirectory())
+                await visit(file);
+            else if (entry.isFile()) {
+                const info = await stat(file);
+                total += info.size;
+                if (total > 64 * 1024 * 1024 || files.length >= 10_000)
+                    throw new Error('Skill source exceeds the comparison limit');
+                files.push({ path: relative(directory, file).split(sep).join('/').replace(ignoreRuntimeFiles ? /^SKILL\.md\.mearl-disabled$/ : /$^/, 'SKILL.md'), bytes: await readFile(file) });
+            }
+        }
+    };
+    await visit(directory);
+    const hash = createHash('sha256');
+    for (const file of files.sort((a, b) => a.path.localeCompare(b.path))) {
+        hash.update(file.path);
+        hash.update(file.bytes);
+    }
+    return hash.digest('hex');
+}
+/** Checks source content in a temporary checkout; never invokes the mutating Skills `check` alias. */
+export async function checkTrackedSkillUpdates(options = {}) {
+    const sources = [...readTrackedSkillSources('global', undefined, options), ...(options.cwd ? readTrackedSkillSources('project', options.cwd, options) : [])];
+    if (sources.some(source => !isPublicSkillSource(source)))
+        throw new Error('Installed Skills require an external manager. Enable its preset.');
+    if (sources.length > 500)
+        throw new Error('Too many tracked Skills to inspect at once');
+    const temporary = await mkdtemp(join(tmpdir(), 'mearl-skill-sources-'));
+    const checkouts = new Map();
+    const runner = options.runCommand ?? runCommand;
+    const updates = [];
+    try {
+        for (const source of sources) {
+            const local = isAbsolute(source.source) ? source.source : undefined;
+            const location = local ? { repository: local } : gitSource(source.source, source.ref);
+            const key = JSON.stringify(location);
+            let checkout = checkouts.get(key);
+            if (!checkout) {
+                const target = join(temporary, String(checkouts.size));
+                checkout = local ? Promise.resolve(local) : (async () => {
+                    const result = await runner('git', ['clone', '--depth', '1', '--filter=blob:none', ...(location.ref ? ['--branch', location.ref] : []), '--', location.repository, target], { capture: true, env: { ...(options.env ?? process.env), GIT_TERMINAL_PROMPT: '0' }, timeoutMs: 120_000 });
+                    if (result.code !== 0)
+                        throw new Error(`Unable to inspect Skill source: ${source.name}`);
+                    return target;
+                })();
+                checkouts.set(key, checkout);
+            }
+            const root = await realpath(await checkout);
+            const directory = await findSkillDirectory(root, source.name, source.skillPath ?? location.subdirectory);
+            let changed;
+            if (source.expectedHash && source.hashKind === 'git-tree' && !local) {
+                const folder = relative(root, directory).split(sep).join('/');
+                const result = await runner('git', ['rev-parse', `HEAD${folder ? ':' + folder : '^{tree}'}`], { cwd: root, capture: true, timeoutMs: 30_000 });
+                if (result.code !== 0 || !/^[a-f\d]{40,64}$/.test(result.stdout.trim()))
+                    throw new Error(`Unable to compare Skill revision: ${source.name}`);
+                changed = result.stdout.trim() !== source.expectedHash;
+            }
+            else if (source.expectedHash && source.hashKind === 'folder')
+                changed = await hashSkillDirectory(directory) !== source.expectedHash;
+            else {
+                const installed = join(source.scope === 'global' ? options.homeDirectory ?? homedir() : options.cwd, '.agents', 'skills', source.name);
+                changed = await hashSkillDirectory(directory, true) !== await hashSkillDirectory(installed, true);
+            }
+            if (changed)
+                updates.push({ name: source.name, source: source.source, scope: source.scope });
+        }
+        return updates;
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+/** 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);
+    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)))
+        return { state: 'conflict', reason: 'SKILL_SOURCE_CONFLICT' };
+    const metadata = readInstalledSkillMetadata(directory);
+    if (!metadata)
+        return { state: 'missing', reason: 'SKILL_NOT_INSTALLED' };
+    if (!tracked)
+        return { state: 'conflict', reason: 'SKILL_SOURCE_UNKNOWN' };
+    if (metadata.name !== name)
+        return { state: 'conflict', reason: 'SKILL_MANIFEST_IDENTITY' };
+    if (version && (!metadata.version || !valid(metadata.version) || !satisfies(metadata.version, version)))
+        return { state: 'version', reason: 'SKILL_VERSION_REQUIRED' };
+    const entry = findPluginDirectoryEntry(directory);
+    const names = listPluginNames().filter(name => {
+        const registered = findPluginRegistration(name)?.entry;
+        return registered !== undefined && resolve(dirname(dirname(registered))) === resolve(directory);
+    });
+    const managedNames = names.filter(name => findPluginRegistration(name)?.managedBy === OFFICIAL_PLUGIN_MANAGER);
+    // User aliases may share a managed Skill without participating in its readiness or cleanup.
+    const requiredNames = managedNames.length ? managedNames : names;
+    if (entry && (requiredNames.length !== 1 || !requiredNames.some(name => {
+        const registration = findPluginRegistration(name);
+        return resolve(registration.entry) === resolve(entry) && !pluginRegistrationNeedsRefresh(registration, true);
+    })))
+        return { state: 'registration', reason: 'SKILL_PLUGIN_REGISTRATION_REQUIRED' };
+    if (!entry && names.length)
+        return { state: 'registration', reason: 'SKILL_PLUGIN_REGISTRATION_REQUIRED' };
+    return { state: 'ready' };
+}

package/dist/skills.d.ts

@@ -0,0 +1,45 @@
+import { inspectGlobalSkill } from './skillSources.js';
+import type { PluginCatalogSelection } from '@mearl/client/plugin';
+import type { ResolvedComponent } from '@mearl/preset';
+import { type CommandRunner, type CommandResult, type RunCommandOptions } from '@mearl/daemon-core';
+export declare const SKILLS_CLI_PACKAGE = "skills@1.5.0";
+export declare const MEARL_SKILL_SOURCE: string;
+export interface ResolveSkillsOptions {
+    env?: NodeJS.ProcessEnv;
+    existsSync?: (filePath: string) => boolean;
+    platform?: NodeJS.Platform;
+    processExecPath?: string;
+}
+export declare function stripAnsi(value: string): string;
+export declare function resolveSkillsExecutable(options?: ResolveSkillsOptions): string | null;
+interface SkillsInvocation {
+    command: string;
+    argsPrefix: string[];
+    env: NodeJS.ProcessEnv;
+}
+export declare function resolveSkillsInvocation(options?: ResolveSkillsOptions): SkillsInvocation | null;
+export interface SkillsCli {
+    id: string;
+    managedSkills: Readonly<Record<string, ResolvedComponent>>;
+    selection?: PluginCatalogSelection;
+    inspectGlobal: typeof inspectGlobalSkill;
+    run(args: string[], options?: Pick<RunCommandOptions, 'capture' | 'tee' | 'cwd' | 'timeoutMs'>): Promise<CommandResult>;
+}
+/** Only the selected manager module is needed; browser and Provider factories stay in their hosts. */
+export declare function captureSkillsCli(options?: ResolveSkillsOptions & {
+    runCommand?: CommandRunner;
+}): Promise<SkillsCli | undefined>;
+export interface InstalledSkill {
+    name: string;
+    path: string;
+    scope: 'global' | 'project';
+}
+export declare function parseInstalledSkills(output: string): InstalledSkill[];
+export declare function parseGlobalMearlSkillPaths(output: string): string[];
+export type MearlSkillOperation = 'install' | 'update' | 'uninstall';
+export declare function runGlobalMearlSkillOperation(operation: MearlSkillOperation, options?: ResolveSkillsOptions & {
+    runCommand?: CommandRunner;
+    yes?: boolean;
+    writeLine?: (line: string) => void;
+}): Promise<boolean>;
+export {};

package/dist/skills.js

@@ -0,0 +1,213 @@
+import path from 'node:path';
+import { SETUP_VERSION } from './setupVersion.js';
+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';
+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';
+const COMMAND_TIMEOUT_MS = 120_000;
+const ANSI_ESCAPE_PATTERN = new RegExp(String.raw `\u001B\[[0-?]*[ -/]*[@-~]`, 'g');
+export function stripAnsi(value) {
+    return value.replace(ANSI_ESCAPE_PATTERN, '');
+}
+export function resolveSkillsExecutable(options = {}) {
+    const candidate = (options.env ?? process.env).MEARL_SKILLS_PATH;
+    const exists = options.existsSync ?? (file => isExecutable(file, options.platform ?? process.platform));
+    return candidate && exists(candidate) ? candidate : null;
+}
+export function resolveSkillsInvocation(options = {}) {
+    const env = options.env ?? process.env;
+    const executable = resolveSkillsExecutable(options);
+    if (executable) {
+        return {
+            command: executable,
+            argsPrefix: [],
+            env: prependNodePath(prependCommandPath(executable, env)),
+        };
+    }
+    const processExecPath = options.processExecPath ?? process.execPath;
+    const npx = findExecutable('npx', {
+        env,
+        existsSync: options.existsSync,
+        platform: options.platform,
+        extraDirectories: [path.dirname(processExecPath)],
+    });
+    if (!npx)
+        return null;
+    return {
+        command: npx,
+        argsPrefix: ['-y', SKILLS_CLI_PACKAGE],
+        env: prependNodePath(prependCommandPath(npx, env), processExecPath),
+    };
+}
+/** Only the selected manager module is needed; browser and Provider factories stay in their hosts. */
+export async function captureSkillsCli(options = {}) {
+    const env = options.env ?? process.env;
+    const runner = options.runCommand ?? runCommand;
+    const directory = env.MEARL_CAPABILITY_DIR || path.join(homedir(), '.mearl', 'capabilities');
+    const current = await new PresetInstallationStore({ directory }).current({ verifyResources: false });
+    const registry = new NodeCapabilityRegistry({ env: Object.freeze({ ...env }), runCommand: runner }, directory, { hooks: ['skills.manager'] });
+    await registry.refresh();
+    if (current.activation?.revision !== registry.revision || current.activation?.installationRevision !== registry.installationRevision)
+        throw new Error('SKILL_MANAGER_CHANGED');
+    const readSources = (scope, cwd) => readTrackedSkillSources(scope, cwd, { env });
+    const selection = current.rawHash ? { path: path.resolve(directory, 'active-node.json'), sha256: current.rawHash } : undefined;
+    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 || 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) => {
+                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');
+                return result;
+            } };
+    }
+    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 }) };
+}
+export function parseInstalledSkills(output) {
+    const value = JSON.parse(stripAnsi(output).trim());
+    if (!Array.isArray(value) || value.some(item => !item || typeof item.name !== 'string' || typeof item.path !== 'string' || !['global', 'project'].includes(item.scope)))
+        throw new Error('Skills returned an invalid skill list');
+    return value;
+}
+export function parseGlobalMearlSkillPaths(output) {
+    const parsed = parseInstalledSkills(output);
+    return [
+        ...new Set(parsed.flatMap((skill) => skill.name === 'mearl' &&
+            skill.scope === 'global' &&
+            typeof skill.path === 'string' &&
+            skill.path.trim()
+            ? [skill.path.trim()]
+            : [])),
+    ];
+}
+export async function runGlobalMearlSkillOperation(operation, options = {}) {
+    const runner = options.runCommand ?? runCommand;
+    const writeLine = options.writeLine ?? (line => console.error(line));
+    let cli;
+    try {
+        cli = await captureSkillsCli({ ...options, runCommand: runner });
+    }
+    catch (error) {
+        writeLine(`Skill: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+    if (!cli) {
+        writeLine('Skill: skills and npx are both unavailable.');
+        return false;
+    }
+    if (operation !== 'uninstall' && cli.managedSkills.mearl) {
+        const owned = cli.managedSkills.mearl;
+        let status;
+        try {
+            status = cli.inspectGlobal(owned.source, 'mearl', owned.version);
+        }
+        catch (error) {
+            writeLine(`Skill: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+        if (status.state !== 'ready') {
+            writeLine(`Skill: preset-managed Mearl requires preset apply/update (${status.reason}).`);
+            return false;
+        }
+        writeLine('Skill: retained the Mearl Skill managed by the selected preset.');
+        return true;
+    }
+    const run = async (args, capture) => {
+        try {
+            return await cli.run(args, {
+                capture,
+                timeoutMs: COMMAND_TIMEOUT_MS,
+            });
+        }
+        catch (error) {
+            writeLine(`Skill: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    };
+    const listMearlPaths = async () => {
+        const listed = await run(['list', '--global', '--json'], true);
+        if (!listed)
+            return null;
+        if (listed.code !== 0) {
+            writeLine(`Skill: unable to list global skills (exit ${listed.code}).`);
+            const detail = stripAnsi(listed.stderr || listed.stdout).trim();
+            if (detail)
+                writeLine(detail);
+            return null;
+        }
+        try {
+            return parseGlobalMearlSkillPaths(listed.stdout);
+        }
+        catch (error) {
+            writeLine(`Skill: ${error instanceof Error ? error.message : String(error)}.`);
+            return null;
+        }
+    };
+    if (operation === 'install') {
+        const installed = await run([
+            'add',
+            MEARL_SKILL_SOURCE,
+            '--skill',
+            'mearl',
+            '--global',
+            ...(options.yes ? ['--yes'] : []),
+        ], false);
+        if (!installed)
+            return false;
+        if (installed.code !== 0) {
+            writeLine(`Skill: install failed (exit ${installed.code}).`);
+            return false;
+        }
+        const installedPaths = await listMearlPaths();
+        if (!installedPaths || installedPaths.length === 0) {
+            writeLine('Skill: installation finished without a tracked global mearl skill.');
+            return false;
+        }
+        writeLine('Skill: installed.');
+        return true;
+    }
+    const paths = await listMearlPaths();
+    if (!paths)
+        return false;
+    if (paths.length === 0) {
+        writeLine('Skill: no tracked global mearl skill found; skipped.');
+        return true;
+    }
+    writeLine('Skill installation:');
+    paths.forEach(skillPath => writeLine(`  ${skillPath}`));
+    const args = operation === 'update'
+        ? ['add', MEARL_SKILL_SOURCE, '--skill', 'mearl', '--global', '--yes']
+        : ['remove', 'mearl', '--global', '--yes'];
+    const result = await run(args, true);
+    if (!result)
+        return false;
+    if (result.code !== 0) {
+        writeLine(`Skill: ${operation} failed (exit ${result.code}).`);
+        return false;
+    }
+    const detail = stripAnsi(`${result.stdout}
+${result.stderr}`).trim();
+    if (detail)
+        writeLine(detail);
+    if (/Failed to (?:update|remove)\s+[1-9]\d*\s+skills?/i.test(detail) || (operation === 'update' && !/\bInstalled [1-9]\d* skills?\b/.test(detail))) {
+        writeLine(`Skill: ${operation} failed.`);
+        return false;
+    }
+    const remainingPaths = await listMearlPaths();
+    if (!remainingPaths || (operation === 'uninstall' ? remainingPaths.length !== 0 : remainingPaths.length === 0)) {
+        writeLine(`Skill: ${operation} did not reach the expected installation state.`);
+        return false;
+    }
+    writeLine(`Skill: ${operation === 'update' ? 'updated' : 'uninstalled'}.`);
+    return true;
+}

package/dist/version.d.ts

@@ -20,3 +20,5 @@ export declare function mearlReleaseLineForVersion(version: string): string;
 export declare function isMearlReleaseVersionInLine(version: string, releaseLine: string): boolean;
 export declare function compareMearlReleaseLines(leftVersion: string, rightVersion: string): -1 | 0 | 1;
 export declare function compareMearlReleaseVersions(leftVersion: string, rightVersion: string): -1 | 0 | 1;
+/** Explicit release lines win; beta setup keeps all runtime packages on its own release. */
+export declare function mearlPackageSelector(setupVersion: string, targetLine?: string): string;

package/dist/version.js

@@ -97,3 +97,9 @@ export function compareMearlReleaseVersions(leftVersion, rightVersion) {
         return 1;
     return 0;
 }
+/** Explicit release lines win; beta setup keeps all runtime packages on its own release. */
+export function mearlPackageSelector(setupVersion, targetLine) {
+    if (targetLine)
+        return targetLine;
+    return parseMearlReleaseVersion(setupVersion)?.channel === 'beta' ? setupVersion : 'latest';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "2.21.0",
+  "version": "3.0.0-beta.0",
   "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",
@@ -14,10 +14,6 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./ali-skills": {
-      "types": "./dist/aliSkills.d.ts",
-      "import": "./dist/aliSkills.js"
-    },
     "./package-manager": {
       "types": "./dist/packageManager.d.ts",
       "import": "./dist/packageManager.js"
@@ -37,6 +33,18 @@
     "./browser-extension": {
       "types": "./dist/browserExtension.d.ts",
       "import": "./dist/browserExtension.js"
+    },
+    "./skills": {
+      "types": "./dist/skills.d.ts",
+      "import": "./dist/skills.js"
+    },
+    "./skill-sources": {
+      "types": "./dist/skillSources.d.ts",
+      "import": "./dist/skillSources.js"
+    },
+    "./preset": {
+      "types": "./dist/preset.d.ts",
+      "import": "./dist/preset.js"
     }
   },
   "bin": {
@@ -54,7 +62,7 @@
     "update",
     "uninstall"
   ],
-  "license": "ISC",
+  "license": "Apache-2.0",
   "engines": {
     "node": ">=22.12.0"
   },
@@ -65,14 +73,18 @@
     "commander": "^15.0.0",
     "extract-zip": "^2.0.1",
     "ws": "^8.18.3",
-    "@mearl/client": "2.21.0",
-    "@mearl/provider": "2.21.0",
-    "@mearl/daemon-core": "2.21.0"
+    "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"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",
     "@types/ws": "^8.18.1",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "@types/semver": "^7.7.1"
   },
   "scripts": {
     "build": "rm -rf dist/ && tsc && chmod +x dist/bin.js",

package/dist/aliSkills.d.ts

@@ -1,32 +0,0 @@
-import fs from 'node:fs';
-import { type CommandRunner } from '@mearl/daemon-core';
-export interface AliSkillsCliOutput {
-    stdout: string;
-    stderr: string;
-}
-export type AliSkillsCliRunner = (executable: string, args: string[], cwd?: string) => Promise<AliSkillsCliOutput>;
-export interface ResolveAliSkillsOptions {
-    env?: NodeJS.ProcessEnv;
-    existsSync?: (filePath: string) => boolean;
-    homedir?: () => string;
-    platform?: NodeJS.Platform;
-    processExecPath?: string;
-    readdirSync?: typeof fs.readdirSync;
-}
-export declare function stripAnsi(value: string): string;
-export declare function resolveAliSkillsExecutable(options?: ResolveAliSkillsOptions): string | null;
-export declare const runAliSkillsCli: AliSkillsCliRunner;
-interface AliSkillsInvocation {
-    command: string;
-    argsPrefix: string[];
-    env: NodeJS.ProcessEnv;
-}
-export declare function resolveAliSkillsInvocation(options?: ResolveAliSkillsOptions): AliSkillsInvocation | null;
-export declare function parseGlobalMearlSkillPaths(output: string): string[];
-export type MearlSkillOperation = 'install' | 'update' | 'uninstall';
-export declare function runGlobalMearlSkillOperation(operation: MearlSkillOperation, options?: ResolveAliSkillsOptions & {
-    runCommand?: CommandRunner;
-    yes?: boolean;
-    writeLine?: (line: string) => void;
-}): Promise<boolean>;
-export {};