@mearl/setup 3.0.0 → 3.0.2

package/dist/skillSources.d.ts

@@ -1,6 +1,6 @@
 import { type CommandRunner } from '@mearl/daemon-core';
 import { readTrackedSkillSources, type SourceOptions, type SkillSourceScope, type TrackedSkillSource } from './skillSourceReceipts.js';
-export { isPublicSkillSource, matchesTrackedSkillSource, readTrackedSkillSources } 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>;

package/dist/skillSources.js

@@ -6,12 +6,15 @@ import { homedir, tmpdir } from 'node:os';
 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, getSkillEnabled, 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';
-import { gitSource, isPublicSkillSource, matchesTrackedSkillSource, readTrackedSkillSources } from './skillSourceReceipts.js';
-export { isPublicSkillSource, matchesTrackedSkillSource, readTrackedSkillSources } from './skillSourceReceipts.js';
+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();
+    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) {
@@ -47,7 +50,8 @@ export async function hashSkillDirectory(directory, ignoreRuntimeFiles = false)
     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)))
+            if (['.git', 'node_modules'].includes(entry.name) ||
+                (ignoreRuntimeFiles && ['__pycache__', '.DS_Store'].includes(entry.name)))
                 continue;
             const file = join(current, entry.name);
             if (entry.isDirectory())
@@ -57,7 +61,13 @@ export async function hashSkillDirectory(directory, ignoreRuntimeFiles = false)
                 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) });
+                files.push({
+                    path: relative(directory, file)
+                        .split(sep)
+                        .join('/')
+                        .replace(ignoreRuntimeFiles ? /^SKILL\.md\.mearl-disabled$/ : /$^/, 'SKILL.md'),
+                    bytes: await readFile(file),
+                });
             }
         }
     };
@@ -71,7 +81,10 @@ export async function hashSkillDirectory(directory, ignoreRuntimeFiles = false)
 }
 /** 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) : [])];
+    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)
@@ -88,12 +101,27 @@ export async function checkTrackedSkillUpdates(options = {}) {
             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;
-                })();
+                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);
@@ -107,10 +135,12 @@ export async function checkTrackedSkillUpdates(options = {}) {
                 changed = result.stdout.trim() !== source.expectedHash;
             }
             else if (source.expectedHash && source.hashKind === 'folder')
-                changed = await hashSkillDirectory(directory) !== source.expectedHash;
+                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);
+                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 });
@@ -128,7 +158,10 @@ export function readLinkedSkillSource(directory, name) {
             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,
+            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);
@@ -169,29 +202,44 @@ function canonicalPath(path) {
         return parent === absolute ? absolute : join(canonicalPath(parent), basename(absolute));
     }
 }
-function hasOnlySetupRegistrations(directory) {
+function hasOnlySetupRegistrations(directory, allowUnregistered = false) {
     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);
+    const registrations = listPluginNames()
+        .flatMap(name => findPluginRegistration(name) ?? [])
+        .filter(registration => contains(resolve(directory), resolve(registration.entry)) ||
+        contains(canonicalPath(directory), canonicalPath(registration.entry)));
+    return ((allowUnregistered || 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(options.homeDirectory ?? homedir(), '.agents', 'skills', name);
-    if (existsSync(join(directory, 'SKILL.md')) && existsSync(join(directory, DISABLED_SKILL_MANIFEST)))
+    if (existsSync(join(directory, 'SKILL.md')) &&
+        existsSync(join(directory, DISABLED_SKILL_MANIFEST)))
         return { state: 'conflict', reason: 'SKILL_MANIFEST_CONFLICT' };
-    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 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' };
+        if (receipt &&
+            (options.externalManager || isPublicSkillSource(receipt)) &&
+            metadata?.name === name) {
+            // A missing ref requires installing the requested ref before the Skill can be ready.
+            const missingRef = matchesTrackedSkillSource(source, receipt, options.normalizeSource, 'missing');
+            const declaredMigration = options.migrateFrom?.some(previous => matchesTrackedSkillSource(previous, receipt, options.normalizeSource));
+            if ((missingRef || declaredMigration) && hasOnlySetupRegistrations(directory, missingRef)) {
+                return { state: 'migration', reason: 'SKILL_SOURCE_MIGRATION_REQUIRED' };
+            }
         }
         return { state: 'conflict', reason: 'SKILL_SOURCE_CONFLICT' };
     }
@@ -202,7 +250,8 @@ export function inspectGlobalSkill(source, name, version, options = {}) {
         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)))
+    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 => {
@@ -212,10 +261,13 @@ export function inspectGlobalSkill(source, name, version, options = {}) {
     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);
-    })))
+    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' };

package/dist/skills.d.ts

@@ -2,7 +2,7 @@ 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 SKILLS_CLI_PACKAGE = "skills";
 export declare const MEARL_SKILL_SOURCE: string;
 export interface ResolveSkillsOptions {
     env?: NodeJS.ProcessEnv;

package/dist/skills.js

@@ -5,7 +5,7 @@ import { NodeCapabilityRegistry } from '@mearl/daemon-core/capabilities';
 import { inspectGlobalSkill, readTrackedSkillSources } from './skillSources.js';
 import { PresetInstallationStore } from './presetStore.js';
 import { findExecutable, isExecutable, npmExecEnvironment, prependCommandPath, prependNodePath, runCommand, } from '@mearl/daemon-core';
-export const SKILLS_CLI_PACKAGE = 'skills@1.5.0';
+export const SKILLS_CLI_PACKAGE = 'skills';
 export const MEARL_SKILL_SOURCE = SETUP_VERSION.includes('-beta.')
     ? `https://github.com/mearlhq/mearl/tree/v${SETUP_VERSION}`
     : 'https://github.com/mearlhq/mearl';
@@ -40,7 +40,7 @@ export function resolveSkillsInvocation(options = {}) {
         return null;
     return {
         command: npx,
-        argsPrefix: ['-y', SKILLS_CLI_PACKAGE],
+        argsPrefix: ['-y', `--package=${SKILLS_CLI_PACKAGE}`, '--', 'skills'],
         env: npmExecEnvironment(prependNodePath(prependCommandPath(npx, env), processExecPath)),
     };
 }
@@ -49,37 +49,81 @@ 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 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)
+    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 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?.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')
+        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, inspection) => inspectGlobalSkill(source, name, version, { migrateFrom: inspection?.migrateFrom, externalManager: true, normalizeSource: backend.normalizeSource, readSources: backend.readSources ?? 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')
+                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, inspection) => inspectGlobalSkill(source, name, version, { migrateFrom: inspection?.migrateFrom, 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());
-    if (!Array.isArray(value) || value.some(item => !item || typeof item.name !== 'string' || typeof item.path !== 'string' || !['global', 'project'].includes(item.scope)))
+    if (!Array.isArray(value))
         throw new Error('Skills returned an invalid skill list');
-    return value;
+    const installed = [];
+    for (const item of value) {
+        if (!item || typeof item.name !== 'string' || !['global', 'project'].includes(item.scope))
+            throw new Error('Skills returned an invalid skill list');
+        if (item.status === 'missing' && item.path === null)
+            continue;
+        if (typeof item.path !== 'string')
+            throw new Error('Skills returned an invalid skill list');
+        installed.push(item);
+    }
+    return installed;
 }
 export function parseGlobalMearlSkillPaths(output) {
     const parsed = parseInstalledSkills(output);
@@ -201,12 +245,14 @@ export async function runGlobalMearlSkillOperation(operation, options = {}) {
 ${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))) {
+    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)) {
+    if (!remainingPaths ||
+        (operation === 'uninstall' ? remainingPaths.length !== 0 : remainingPaths.length === 0)) {
         writeLine(`Skill: ${operation} did not reach the expected installation state.`);
         return false;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",
@@ -79,11 +79,11 @@
     "ws": "^8.18.3",
     "semver": "^7.8.5",
     "adm-zip": "^0.6.1",
-    "@mearl/client": "3.0.0",
-    "@mearl/provider": "3.0.0",
-    "@mearl/daemon-core": "3.0.0",
-    "@mearl/preset": "3.0.0",
-    "@mearl/browser-core": "3.0.0"
+    "@mearl/provider": "3.0.2",
+    "@mearl/preset": "3.0.2",
+    "@mearl/browser-core": "3.0.2",
+    "@mearl/daemon-core": "3.0.2",
+    "@mearl/client": "3.0.2"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",