@mearl/setup 2.2.2 → 2.4.0

package/README.md

@@ -18,6 +18,18 @@ npx @mearl/setup <install|update|uninstall> [--local|--cloud|--mcp] [--yes]
 - 卸载一个环境但另一个仍依赖全局 mearl skill 时会保留 skill。
 - `--mcp` 的客户端配置和清理由 `@mearl/mcp-server` 自己的命令完成。
 
+## 跟随浏览器扩展自动更新
+
+浏览器扩展与 Native Host 首次建联时会交换版本。每次扩展后台启动只检查一次；当扩展
+进入更高的 `major.minor` release line 时，旧 Host 会在保持当前连接可用的前提下，调用
+对应 `major.minor.x` 范围内最新的 `@mearl/setup`，把 `@mearl/native-host` 与
+`@mearl/client` 一起更新到该范围内的最新版本。成功后 Host 退出，扩展通过已有重连机制
+启动新版本。只有两个本地 CLI 版本一致且都属于扩展的 release line 时，更新才会被视为成功。
+
+自动更新不会降级较新的 Host，也不会改动 cloud、MCP 或独立安装的 Mearl Skill。
+目标 npm 版本尚未发布、网络不可用或更新失败时，旧 Host 会继续运行；下一次扩展后台
+生命周期可重新尝试，也可手动执行 `npx @mearl/setup update --local`。
+
 ## 人工与 Agent 使用
 
 - 人工在终端执行时不加 `--yes`，需要选择 Skill 安装目标或 MCP 客户端时会显示交互提示。

package/dist/aliSkills.js

@@ -2,33 +2,13 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
-import { executableNames, findExecutable, isExecutable, prependCommandPath, prependNodePath, resolveSpawnCommand, runCommand, } from './process.js';
+import { executableNames, findExecutable, isExecutable, prependCommandPath, prependNodePath, resolveSpawnCommand, runCommand, versionManagerExecutableCandidates, } from './process.js';
 const COMMAND_TIMEOUT_MS = 120_000;
 const MAX_OUTPUT_LENGTH = 1_000_000;
 const ANSI_ESCAPE_PATTERN = new RegExp(String.raw `\u001B\[[0-?]*[ -/]*[@-~]`, 'g');
 function existingExecutable(candidates, existsSync) {
     return candidates.find(candidate => candidate && existsSync(candidate)) ?? null;
 }
-function versionManagerCandidates(home, executableNames, readdirSync) {
-    const roots = [
-        path.join(home, '.nvm', 'versions', 'node'),
-        path.join(home, '.fnm', 'node-versions'),
-    ];
-    return roots.flatMap(root => {
-        try {
-            return readdirSync(root, { withFileTypes: true })
-                .filter(entry => entry.isDirectory())
-                .sort((left, right) => right.name.localeCompare(left.name, undefined, { numeric: true }))
-                .flatMap(entry => executableNames.flatMap(name => [
-                path.join(root, entry.name, 'bin', name),
-                path.join(root, entry.name, 'installation', 'bin', name),
-            ]));
-        }
-        catch {
-            return [];
-        }
-    });
-}
 export function stripAnsi(value) {
     return value.replace(ANSI_ESCAPE_PATTERN, '');
 }
@@ -53,7 +33,11 @@ export function resolveAliSkillsExecutable(options = {}) {
         ...names.map(name => path.join(home, '.volta', 'bin', name)),
         ...names.map(name => path.join(home, '.local', 'share', 'pnpm', name)),
         ...names.map(name => path.join(home, 'Library', 'pnpm', name)),
-        ...versionManagerCandidates(home, names, readdirSync),
+        ...versionManagerExecutableCandidates(home, names, {
+            env,
+            platform,
+            readdirSync,
+        }),
         ...(platform === 'win32'
             ? []
             : ['/opt/homebrew/bin/ali-skills', '/usr/local/bin/ali-skills', '/usr/bin/ali-skills']),

package/dist/cli.d.ts

@@ -5,6 +5,8 @@ interface ParsedArgs {
     help: boolean;
     operation?: MearlLifecycleOperation;
     profile?: MearlProfile;
+    skipSkill: boolean;
+    targetLine?: string;
     yes: boolean;
 }
 export declare function parseSetupArgs(argv: string[]): ParsedArgs;

package/dist/cli.js

@@ -2,21 +2,38 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runMearlLifecycle } from './lifecycle.js';
+import { isMearlReleaseLine } from './version.js';
 export function parseSetupArgs(argv) {
     if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
-        return { help: true, yes: false };
+        return { help: true, skipSkill: false, yes: false };
     }
     const operation = argv[0];
     if (operation !== 'install' && operation !== 'update' && operation !== 'uninstall') {
         throw new Error(`Unknown operation: ${operation}`);
     }
     let profile;
+    let skipSkill = false;
+    let targetLine;
     let yes = false;
-    for (const arg of argv.slice(1)) {
+    for (let index = 1; index < argv.length; index += 1) {
+        const arg = argv[index];
         if (arg === '--yes' || arg === '-y' || arg === '--non-interactive') {
             yes = true;
             continue;
         }
+        if (arg === '--skip-skill') {
+            skipSkill = true;
+            continue;
+        }
+        if (arg === '--target-line') {
+            const value = argv[index + 1];
+            if (!isMearlReleaseLine(value)) {
+                throw new Error('--target-line requires a valid Mearl release line such as 2.3.x');
+            }
+            targetLine = value;
+            index += 1;
+            continue;
+        }
         const candidate = arg === '--local'
             ? 'local'
             : arg === '--cloud'
@@ -31,7 +48,10 @@ export function parseSetupArgs(argv) {
         }
         profile = candidate;
     }
-    return { help: false, operation, profile, yes };
+    if (operation === 'uninstall' && targetLine) {
+        throw new Error('--target-line is not available for uninstall');
+    }
+    return { help: false, operation, profile, skipSkill, targetLine, yes };
 }
 function printHelp() {
     console.error(`Mearl Setup
@@ -48,6 +68,9 @@ Options:
   --local      Manage @mearl/native-host and @mearl/client
   --cloud      Manage @mearl/cloud-client
   --mcp        Manage @mearl/mcp-server and its configuration
+  --target-line <major.minor.x>
+               Install the latest packages from one release line, such as 2.3.x
+  --skip-skill Keep the independently managed Mearl Skill unchanged
   --yes, -y    Run without prompts and accept detected defaults
   --non-interactive
                Alias for --yes, intended for Agents and CI
@@ -58,6 +81,7 @@ Examples:
   npx @mearl/setup install --yes
   npx @mearl/setup install --cloud
   npx @mearl/setup update
+  npx @mearl/setup update --local --target-line 2.3.x --skip-skill
   npx @mearl/setup uninstall --local`);
 }
 export async function main(argv = process.argv.slice(2), interactiveTerminal = process.stdin.isTTY === true && process.stdout.isTTY === true) {
@@ -82,6 +106,8 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
         const ok = await runMearlLifecycle({
             operation: parsed.operation,
             profile: parsed.profile,
+            skipSkill: parsed.skipSkill,
+            targetLine: parsed.targetLine,
             yes: parsed.yes,
         });
         return ok ? 0 : 1;

package/dist/index.d.ts

@@ -5,4 +5,6 @@ export type { MearlLifecycleDependencies, MearlLifecycleOperation, MearlLifecycl
 export { MEARL_PROFILES, detectMearlProfiles } from './profiles.js';
 export type { DetectedMearlProfiles, MearlProfile, MearlProfileConfig } from './profiles.js';
 export { MEARL_NATIVE_HOST_NAMES, resolveNativeHostDirectory, uninstallNativeHostArtifacts, } from './nativeHost.js';
+export { compareMearlReleaseLines, isMearlReleaseLine, isMearlReleaseVersion, isMearlReleaseVersionInLine, mearlReleaseLineForVersion, parseMearlReleaseLine, parseMearlReleaseVersion, } from './version.js';
+export type { MearlReleaseLine, MearlReleaseVersion } from './version.js';
 export type { NativeHostCleanupDependencies, NativeHostCleanupOptions, NativeHostIntegrationMode, } from './nativeHost.js';

package/dist/index.js

@@ -2,3 +2,4 @@ export { buildGlobalPackageCommand, detectGlobalPackage, resolveInvokingPackageM
 export { runMearlLifecycle } from './lifecycle.js';
 export { MEARL_PROFILES, detectMearlProfiles } from './profiles.js';
 export { MEARL_NATIVE_HOST_NAMES, resolveNativeHostDirectory, uninstallNativeHostArtifacts, } from './nativeHost.js';
+export { compareMearlReleaseLines, isMearlReleaseLine, isMearlReleaseVersion, isMearlReleaseVersionInLine, mearlReleaseLineForVersion, parseMearlReleaseLine, parseMearlReleaseVersion, } from './version.js';

package/dist/lifecycle.d.ts

@@ -8,6 +8,8 @@ export interface MearlLifecycleOptions {
     operation: MearlLifecycleOperation;
     profile?: MearlProfile;
     yes?: boolean;
+    targetLine?: string;
+    skipSkill?: boolean;
     env?: NodeJS.ProcessEnv;
 }
 export interface MearlLifecycleDependencies {

package/dist/lifecycle.js

@@ -7,6 +7,7 @@ import { buildGlobalPackageCommand, detectGlobalPackage, resolveInvokingPackageM
 import { MEARL_PROFILES, detectMearlProfiles, } from './profiles.js';
 import { uninstallNativeHostArtifacts } from './nativeHost.js';
 import { executableNames, prependCommandPath, runCommand, } from './process.js';
+import { isMearlReleaseLine } from './version.js';
 async function confirmInTerminal(message) {
     if (!input.isTTY || !output.isTTY)
         return false;
@@ -85,6 +86,9 @@ function operationVerb(operation) {
     return operation === 'uninstall' ? 'uninstall' : operation === 'update' ? 'update' : 'install';
 }
 export async function runMearlLifecycle(options, dependencies = {}) {
+    if (options.targetLine && !isMearlReleaseLine(options.targetLine)) {
+        throw new Error('targetLine must be a valid Mearl release line such as 2.3.x');
+    }
     const env = options.env ?? process.env;
     const writeLine = dependencies.writeLine ?? (line => console.error(line));
     const existsSync = dependencies.existsSync ?? fs.existsSync;
@@ -158,7 +162,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
             continue;
         }
         const packageOperation = options.operation === 'uninstall' ? 'uninstall' : options.operation;
-        const command = buildGlobalPackageCommand(installation, packageOperation, config.packages);
+        const command = buildGlobalPackageCommand(installation, packageOperation, config.packages, options.targetLine);
         writeLine(`Packages (${profile}): ${command.manager}`);
         const result = await runLifecycleCommand(runner, command.command, command.args, env, `Packages (${profile})`, writeLine);
         if (!result) {
@@ -182,7 +186,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
     }
     let skillOk = true;
     const selectedUsesSkill = selected.some(profile => MEARL_PROFILES[profile].usesSkill);
-    if (packagesOk && selectedUsesSkill) {
+    if (packagesOk && selectedUsesSkill && options.skipSkill !== true) {
         try {
             if (options.operation === 'uninstall') {
                 const remainingSkillProfiles = ['local', 'cloud'].filter(profile => detected.has(profile) && !selected.includes(profile));

package/dist/packageManager.d.ts

@@ -3,8 +3,12 @@ export type PackageOperation = 'install' | 'update' | 'uninstall';
 export interface PackageManagerInstallation {
     manager: GlobalPackageManager;
     command: string;
+    /** Directory containing globally installed package executables. */
+    binDirectory?: string;
 }
-export interface GlobalPackageCommand extends PackageManagerInstallation {
+export interface GlobalPackageCommand {
+    manager: GlobalPackageManager;
+    command: string;
     args: string[];
 }
 export interface DetectedGlobalPackage extends PackageManagerInstallation {
@@ -21,7 +25,7 @@ export interface PackageDetectionOptions {
     realpathSync?: (filePath: string) => string;
 }
 export declare function resolvePackageManagerInstallation(packageRoot: string, packageName: string, options?: PackageDetectionOptions): PackageManagerInstallation | null;
-export declare function buildGlobalPackageCommand(installation: PackageManagerInstallation, operation: PackageOperation, packages: string[]): GlobalPackageCommand;
+export declare function buildGlobalPackageCommand(installation: PackageManagerInstallation, operation: PackageOperation, packages: string[], targetSelector?: string): GlobalPackageCommand;
 export declare function resolveInvokingPackageManager(options?: {
     env?: NodeJS.ProcessEnv;
     existsSync?: (filePath: string) => boolean;

package/dist/packageManager.js

@@ -29,26 +29,48 @@ export function resolvePackageManagerInstallation(packageRoot, packageName, opti
             ...executableNames('pnpm', platform).map(name => path.join(pnpmHome, name)),
             ...executableNames('pnpm', platform).map(name => path.join(path.dirname(processExecPath), name)),
         ], existsSync) ?? fallbackCommand('pnpm', platform);
-        return { manager: 'pnpm', command };
+        return { manager: 'pnpm', command, binDirectory: pnpmHome };
     }
     const bunMarker = `/.bun/install/global/node_modules/${lowerPackageName}`;
     if (lowerRoot.endsWith(bunMarker)) {
         const bunHome = normalizedRoot.slice(0, lowerRoot.indexOf('/.bun/'));
         const command = firstExisting(executableNames('bun', platform).map(name => path.join(bunHome, '.bun', 'bin', name)), existsSync) ?? fallbackCommand('bun', platform);
-        return { manager: 'bun', command };
+        return {
+            manager: 'bun',
+            command,
+            binDirectory: path.join(bunHome, '.bun', 'bin'),
+        };
     }
     if ((lowerRoot.includes('/.config/yarn/global/node_modules/') ||
         lowerRoot.includes('/.yarn/global/node_modules/') ||
         lowerRoot.includes('/yarn/global/node_modules/') ||
         lowerRoot.includes('/yarn/data/global/node_modules/')) &&
         lowerRoot.endsWith(`/node_modules/${lowerPackageName}`)) {
-        return { manager: 'yarn', command: fallbackCommand('yarn', platform) };
+        const layout = [
+            { marker: '/.config/yarn/global/', binSegments: ['.yarn', 'bin'] },
+            { marker: '/.yarn/global/', binSegments: ['.yarn', 'bin'] },
+            { marker: '/yarn/data/global/', binSegments: ['yarn', 'bin'] },
+            { marker: '/yarn/global/', binSegments: ['yarn', 'bin'] },
+        ].find(candidate => lowerRoot.includes(candidate.marker));
+        const prefix = normalizedRoot.slice(0, lowerRoot.indexOf(layout.marker));
+        const binDirectory = path.join(prefix, ...layout.binSegments);
+        const command = firstExisting([
+            ...executableNames('yarn', platform).map(name => path.join(binDirectory, name)),
+            ...executableNames('yarn', platform).map(name => path.join(path.dirname(processExecPath), name)),
+        ], existsSync) ??
+            findExecutable('yarn', { env, existsSync, platform }) ??
+            fallbackCommand('yarn', platform);
+        return { manager: 'yarn', command, binDirectory };
     }
     if (lowerRoot.includes('/.volta/tools/image/packages/') &&
         lowerRoot.endsWith(`/lib/node_modules/${lowerPackageName}`)) {
         const voltaHome = normalizedRoot.slice(0, lowerRoot.indexOf('/.volta/'));
         const command = firstExisting(executableNames('volta', platform).map(name => path.join(voltaHome, '.volta', 'bin', name)), existsSync) ?? fallbackCommand('volta', platform);
-        return { manager: 'volta', command };
+        return {
+            manager: 'volta',
+            command,
+            binDirectory: path.join(voltaHome, '.volta', 'bin'),
+        };
     }
     const npmMarker = `/lib/node_modules/${lowerPackageName}`;
     if (lowerRoot.endsWith(npmMarker)) {
@@ -57,18 +79,25 @@ export function resolvePackageManagerInstallation(packageRoot, packageName, opti
             ...executableNames('npm', platform).map(name => path.join(prefix, 'bin', name)),
             ...executableNames('npm', platform).map(name => path.join(path.dirname(processExecPath), name)),
         ], existsSync) ?? fallbackCommand('npm', platform);
-        return { manager: 'npm', command };
+        return { manager: 'npm', command, binDirectory: path.join(prefix, 'bin') };
     }
     if (platform === 'win32' && env.APPDATA) {
         const npmRoot = normalizePath(path.join(env.APPDATA, 'npm', 'node_modules', packageName));
         if (lowerRoot === npmRoot.toLowerCase()) {
-            return { manager: 'npm', command: fallbackCommand('npm', platform) };
+            const binDirectory = path.join(env.APPDATA, 'npm');
+            const command = firstExisting([
+                ...executableNames('npm', platform).map(name => path.join(binDirectory, name)),
+                ...executableNames('npm', platform).map(name => path.join(path.dirname(processExecPath), name)),
+            ], existsSync) ?? fallbackCommand('npm', platform);
+            return { manager: 'npm', command, binDirectory };
         }
     }
     return null;
 }
-export function buildGlobalPackageCommand(installation, operation, packages) {
-    const targets = operation === 'uninstall' ? packages : packages.map(packageName => `${packageName}@latest`);
+export function buildGlobalPackageCommand(installation, operation, packages, targetSelector = 'latest') {
+    const targets = operation === 'uninstall'
+        ? packages
+        : packages.map(packageName => `${packageName}@${targetSelector}`);
     let args;
     switch (installation.manager) {
         case 'npm':
@@ -91,7 +120,7 @@ export function buildGlobalPackageCommand(installation, operation, packages) {
             args = operation === 'uninstall' ? ['uninstall', ...targets] : ['install', ...targets];
             break;
     }
-    return { ...installation, args };
+    return { manager: installation.manager, command: installation.command, args };
 }
 export function resolveInvokingPackageManager(options = {}) {
     const env = options.env ?? process.env;
@@ -194,7 +223,13 @@ export function detectGlobalPackage(packageName, binNames, options = {}) {
         });
         if (!installation)
             continue;
-        return { packageName, packageRoot, executable, ...installation };
+        return {
+            packageName,
+            packageRoot,
+            executable,
+            ...installation,
+            binDirectory: path.dirname(executable),
+        };
     }
     return null;
 }

package/dist/process.d.ts

@@ -1,3 +1,4 @@
+import fs from 'node:fs';
 export interface SpawnCommand {
     command: string;
     args: string[];
@@ -16,9 +17,16 @@ export interface RunCommandOptions {
 export type CommandRunner = (command: string, args: string[], options?: RunCommandOptions) => Promise<CommandResult>;
 export declare function isExecutable(filePath: string, platform?: NodeJS.Platform): boolean;
 export declare function executableNames(name: string, platform?: NodeJS.Platform): string[];
+export interface VersionManagerExecutableCandidateOptions {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    readdirSync?: typeof fs.readdirSync;
+}
+export declare function versionManagerExecutableCandidates(home: string, names: string[], options?: VersionManagerExecutableCandidateOptions): string[];
 export declare function resolveSpawnCommand(executable: string, args: string[], platform?: NodeJS.Platform, commandInterpreter?: string | undefined): SpawnCommand;
 export declare function prependCommandPath(command: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function prependNodePath(env?: NodeJS.ProcessEnv, nodeExecutable?: string): NodeJS.ProcessEnv;
+export declare function prependPathDirectory(directory: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function findExecutable(name: string, options?: {
     env?: NodeJS.ProcessEnv;
     existsSync?: (filePath: string) => boolean;

package/dist/process.js

@@ -14,6 +14,37 @@ export function isExecutable(filePath, platform = process.platform) {
 export function executableNames(name, platform = process.platform) {
     return platform === 'win32' ? [`${name}.cmd`, `${name}.exe`, name] : [name];
 }
+export function versionManagerExecutableCandidates(home, names, options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const readdirSync = options.readdirSync ?? fs.readdirSync;
+    const fnmDefaultRoot = env.XDG_DATA_HOME
+        ? path.join(env.XDG_DATA_HOME, 'fnm')
+        : platform === 'darwin'
+            ? path.join(home, 'Library', 'Application Support', 'fnm')
+            : platform === 'win32' && env.APPDATA
+                ? path.join(env.APPDATA, 'fnm')
+                : path.join(home, '.local', 'share', 'fnm');
+    const roots = [
+        path.join(env.NVM_DIR || path.join(home, '.nvm'), 'versions', 'node'),
+        path.join(env.FNM_DIR || fnmDefaultRoot, 'node-versions'),
+        path.join(home, '.fnm', 'node-versions'),
+    ].filter((root, index, all) => all.indexOf(root) === index);
+    return roots.flatMap(root => {
+        try {
+            return readdirSync(root, { withFileTypes: true })
+                .filter(entry => entry.isDirectory())
+                .sort((left, right) => right.name.localeCompare(left.name, undefined, { numeric: true }))
+                .flatMap(entry => names.flatMap(name => [
+                path.join(root, entry.name, 'bin', name),
+                path.join(root, entry.name, 'installation', 'bin', name),
+            ]));
+        }
+        catch {
+            return [];
+        }
+    });
+}
 export function resolveSpawnCommand(executable, args, platform = process.platform, commandInterpreter = process.env.ComSpec) {
     if (platform === 'win32' && /\.(?:cmd|bat)$/i.test(executable)) {
         return {
@@ -26,12 +57,12 @@ export function resolveSpawnCommand(executable, args, platform = process.platfor
 export function prependCommandPath(command, env = process.env) {
     if (!path.isAbsolute(command))
         return env;
-    return prependPath(path.dirname(command), env);
+    return prependPathDirectory(path.dirname(command), env);
 }
 export function prependNodePath(env = process.env, nodeExecutable = process.execPath) {
-    return prependPath(path.dirname(nodeExecutable), env);
+    return prependPathDirectory(path.dirname(nodeExecutable), env);
 }
-function prependPath(directory, env) {
+export function prependPathDirectory(directory, env = process.env) {
     const pathKey = Object.keys(env).find(key => key.toLowerCase() === 'path') || 'PATH';
     const inherited = env[pathKey] || '';
     const entries = inherited.split(path.delimiter).filter(Boolean);

package/dist/version.d.ts

@@ -0,0 +1,21 @@
+export declare const MEARL_RELEASE_VERSION_MAX_LENGTH = 64;
+export interface MearlReleaseVersion {
+    raw: string;
+    major: number;
+    minor: number;
+    patch: number;
+    channel: 'stable' | 'beta';
+    beta?: number;
+}
+export interface MearlReleaseLine {
+    raw: string;
+    major: number;
+    minor: number;
+}
+export declare function parseMearlReleaseVersion(value: unknown): MearlReleaseVersion | null;
+export declare function isMearlReleaseVersion(value: unknown): value is string;
+export declare function parseMearlReleaseLine(value: unknown): MearlReleaseLine | null;
+export declare function isMearlReleaseLine(value: unknown): value is string;
+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;

package/dist/version.js

@@ -0,0 +1,77 @@
+export const MEARL_RELEASE_VERSION_MAX_LENGTH = 64;
+const RELEASE_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-beta\.(0|[1-9]\d*))?$/;
+const RELEASE_LINE_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.x$/;
+const RELEASE_COMPONENT_MAXIMUM = 65_535;
+function parseComponent(value) {
+    const component = Number(value);
+    return Number.isSafeInteger(component) && component <= RELEASE_COMPONENT_MAXIMUM
+        ? component
+        : null;
+}
+export function parseMearlReleaseVersion(value) {
+    if (typeof value !== 'string' || value.length > MEARL_RELEASE_VERSION_MAX_LENGTH)
+        return null;
+    const match = RELEASE_VERSION_PATTERN.exec(value);
+    if (!match)
+        return null;
+    const major = parseComponent(match[1]);
+    const minor = parseComponent(match[2]);
+    const patch = parseComponent(match[3]);
+    const beta = match[4] === undefined ? undefined : parseComponent(match[4]);
+    if (major === null || minor === null || patch === null || beta === null)
+        return null;
+    return {
+        raw: value,
+        major,
+        minor,
+        patch,
+        channel: beta === undefined ? 'stable' : 'beta',
+        ...(beta === undefined ? {} : { beta }),
+    };
+}
+export function isMearlReleaseVersion(value) {
+    return parseMearlReleaseVersion(value) !== null;
+}
+export function parseMearlReleaseLine(value) {
+    if (typeof value !== 'string' || value.length > MEARL_RELEASE_VERSION_MAX_LENGTH)
+        return null;
+    const match = RELEASE_LINE_PATTERN.exec(value);
+    if (!match)
+        return null;
+    const major = parseComponent(match[1]);
+    const minor = parseComponent(match[2]);
+    if (major === null || minor === null)
+        return null;
+    return { raw: value, major, minor };
+}
+export function isMearlReleaseLine(value) {
+    return parseMearlReleaseLine(value) !== null;
+}
+export function mearlReleaseLineForVersion(version) {
+    const parsed = parseMearlReleaseVersion(version);
+    if (!parsed)
+        throw new Error('A valid Mearl release version is required');
+    return `${parsed.major}.${parsed.minor}.x`;
+}
+export function isMearlReleaseVersionInLine(version, releaseLine) {
+    const parsedVersion = parseMearlReleaseVersion(version);
+    const parsedLine = parseMearlReleaseLine(releaseLine);
+    return (parsedVersion !== null &&
+        parsedLine !== null &&
+        parsedVersion.major === parsedLine.major &&
+        parsedVersion.minor === parsedLine.minor);
+}
+export function compareMearlReleaseLines(leftVersion, rightVersion) {
+    const left = parseMearlReleaseVersion(leftVersion);
+    const right = parseMearlReleaseVersion(rightVersion);
+    if (!left || !right) {
+        throw new Error('Mearl release-line comparison requires valid release versions');
+    }
+    for (const key of ['major', 'minor']) {
+        if (left[key] < right[key])
+            return -1;
+        if (left[key] > right[key])
+            return 1;
+    }
+    return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "2.2.2",
+  "version": "2.4.0",
   "description": "One-shot installer, updater, and uninstaller for Mearl environments",
   "type": "module",
   "main": "dist/index.js",
@@ -18,9 +18,17 @@
       "types": "./dist/process.d.ts",
       "import": "./dist/process.js"
     },
+    "./package-manager": {
+      "types": "./dist/packageManager.d.ts",
+      "import": "./dist/packageManager.js"
+    },
     "./native-host": {
       "types": "./dist/nativeHost.d.ts",
       "import": "./dist/nativeHost.js"
+    },
+    "./version": {
+      "types": "./dist/version.d.ts",
+      "import": "./dist/version.js"
     }
   },
   "bin": {