moluoxixi-ai-rules 0.2.1 → 0.2.3

package/dist/roles/moluoxixi/constants/skills.d.ts

@@ -1,4 +1,5 @@
-import type { VendorRepo } from '../../../scripts/lib/vendors.js';
+import type { RolePackageConfig, VendorRepo } from '../../../scripts/lib/vendors.js';
 export declare const extendsRoles: string[];
 export declare const hosts = "all";
+export declare const packages: RolePackageConfig[];
 export declare const vendors: VendorRepo[];

package/dist/roles/moluoxixi/constants/skills.js

@@ -1,25 +1,37 @@
 export const extendsRoles = [];
 export const hosts = 'all';
+export const packages = [
+    {
+        name: '@moluoxixi/airules-moluoxixi-core',
+        path: 'packages/core',
+    },
+    {
+        name: '@moluoxixi/airules-moluoxixi-cli',
+        path: 'packages/cli',
+        install: {
+            kind: 'npm-global',
+            version: 'latest',
+        },
+    },
+];
 export const vendors = [
     {
         name: 'moluoxixi',
         source: 'https://github.com/moluoxixi/AIRules.git',
-        setup: [
+        projections: [
             {
-                command: 'npm',
-                args: ['install', '--global', '@colbymchenry/codegraph'],
-                skipIfCommandAvailable: 'codegraph',
+                kind: 'role-assets',
+                sourceDir: 'roles/moluoxixi',
             },
             {
-                command: 'codegraph',
-                args: ['install', '--yes'],
-                windowsCommandShim: true,
+                kind: 'namespace',
+                sourceDir: 'skills/common',
+                output: 'common',
             },
-        ],
-        projections: [
             {
-                kind: 'role-assets',
-                sourceDir: 'roles/moluoxixi',
+                kind: 'mcp',
+                sourceFile: 'mcps/code/mcps.json',
+                output: 'mcps/code/mcp.json',
             },
         ],
     },

package/dist/roles/trellis/constants/skills.js

@@ -9,22 +9,22 @@ export const vendors = [
                 command: 'npm',
                 args: ['install', '--global', '@mindfoldhq/trellis@latest'],
             },
-            {
-                command: 'npm',
-                args: ['install', '--global', '@colbymchenry/codegraph'],
-                skipIfCommandAvailable: 'codegraph',
-            },
-            {
-                command: 'codegraph',
-                args: ['install', '--yes'],
-                windowsCommandShim: true,
-            },
         ],
         projections: [
             {
                 kind: 'role-assets',
                 sourceDir: 'roles/trellis',
             },
+            {
+                kind: 'namespace',
+                sourceDir: 'skills/common',
+                output: 'common',
+            },
+            {
+                kind: 'mcp',
+                sourceFile: 'mcps/code/mcps.json',
+                output: 'mcps/code/mcp.json',
+            },
         ],
     },
     {

package/dist/scripts/lib/canonical-path.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Resolve filesystem aliases for every existing ancestor while preserving a
+ * not-yet-created suffix. macOS exposes paths such as /var through a symlink to
+ * /private/var, so lexical path.resolve() alone is not a stable identity.
+ */
+export declare function canonicalPath(input: string): string;
+export declare function canonicalPathKey(input: string): string;
+export declare function areSamePaths(left: string, right: string): boolean;
+export declare function isPathInside(root: string, target: string): boolean;

package/dist/scripts/lib/canonical-path.js

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+function isMissingPathError(error) {
+    return error.code === 'ENOENT';
+}
+function isFilesystemError(error, code) {
+    return error.code === code;
+}
+function lexicalPathKey(input) {
+    const resolved = path.resolve(input).replaceAll('\\', '/');
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+/**
+ * Resolve filesystem aliases for every existing ancestor while preserving a
+ * not-yet-created suffix. macOS exposes paths such as /var through a symlink to
+ * /private/var, so lexical path.resolve() alone is not a stable identity.
+ */
+export function canonicalPath(input) {
+    let current = path.resolve(input);
+    const missingSegments = [];
+    while (true) {
+        try {
+            const existingRoot = fs.realpathSync.native(current);
+            return path.resolve(existingRoot, ...missingSegments.reverse());
+        }
+        catch (error) {
+            if (!isMissingPathError(error)) {
+                throw error;
+            }
+            const parent = path.dirname(current);
+            if (parent === current) {
+                throw error;
+            }
+            missingSegments.push(path.basename(current));
+            current = parent;
+        }
+    }
+}
+export function canonicalPathKey(input) {
+    const resolved = canonicalPath(input).replaceAll('\\', '/');
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+export function areSamePaths(left, right) {
+    if (!left || !right) {
+        return false;
+    }
+    try {
+        return canonicalPathKey(left) === canonicalPathKey(right);
+    }
+    catch (error) {
+        // Equality is used while repairing cyclic links. Containment checks must
+        // remain strict and continue to surface ELOOP through canonicalPath().
+        if (!isFilesystemError(error, 'ELOOP')) {
+            throw error;
+        }
+        return lexicalPathKey(left) === lexicalPathKey(right);
+    }
+}
+export function isPathInside(root, target) {
+    const canonicalRoot = canonicalPath(root);
+    const canonicalTarget = canonicalPath(target);
+    const relative = path.relative(canonicalRoot, canonicalTarget);
+    return relative === ''
+        || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+}

package/dist/scripts/lib/install.d.ts

@@ -8,7 +8,7 @@ export declare function shouldUseShellForSetupCommand(command: string, windowsCo
  * 任一命令失败都会抛出错误，避免安装流程伪装成功。
  * @param manifest 已解析的 VendorManifest
  */
-export declare function runSkillSetupCommands(manifest: VendorManifest): void;
+export declare function runSkillSetupCommands(manifest: VendorManifest, homeDir?: string): void;
 export declare function isSamePath(p1: string, p2: string): boolean;
 export declare function replaceWithSymlink(source: string, target: string, type: 'junction' | 'dir' | 'file'): void;
 export interface InstallPaths {
@@ -52,6 +52,9 @@ export declare function rebuildVendorSkillLinks({ homeDir, manifestPath }: {
  * ~/.agents 是行业标准共享层，始终存在（不存在则创建）。
  */
 export declare function projectSkillsToHost(userHome: string, moluoHome: string, hostSkillsHome: string, options?: SyncFlattenedSkillsOptions): void;
+export declare function readInstalledMcpServers(moluoHome: string, role: string): Record<string, unknown> | undefined;
+export declare function applyMcpServerProjection(servers: Record<string, unknown>, mcp: Pick<McpProjection, 'serverCommandFormat' | 'serverDefaults' | 'serverOverrides'>): Record<string, unknown>;
+export declare function readTomlMcpServerNames(content: string, serversKey: string): Set<string>;
 export declare function projectToHost({ userHome, moluoHome, hostHome, customSkillsDirName, excludedSkills, projectSkills, role, mcpHome, mcp, }: {
     userHome: string;
     moluoHome: string;

package/dist/scripts/lib/install.js

@@ -3,11 +3,13 @@ import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, re
 import os from 'node:os';
 import path from 'node:path';
 import { findHostConfig, resolveGlobalAgentSkillsPath, resolveHostPaths } from '../../constants/hosts.js';
+import { areSamePaths, canonicalPath, canonicalPathKey, isPathInside } from './canonical-path.js';
 import { buildLinkPlan } from './links.js';
+import { loadMcpCatalog, validateMcpServerNames } from './mcp-catalog.js';
 import { requireRoleName } from './role-assets.js';
 import { DEFAULT_ROLE, roleOverlayOrder } from './roles.js';
 import { collectFlattenedSkillSources, discoverSkillDirectories, flattenedSkillName } from './skill-projection.js';
-import { loadVendorManifest } from './vendors.js';
+import { loadVendorManifest, rolePackageSetupCommands } from './vendors.js';
 /** 获取 vendor 技能目录的绝对路径 */
 function vendorSkillsPath(homeDir) {
     return path.join(homeDir, 'vendor', 'skills');
@@ -79,50 +81,58 @@ function isSetupCommandAvailable(command) {
  * 任一命令失败都会抛出错误，避免安装流程伪装成功。
  * @param manifest 已解析的 VendorManifest
  */
-export function runSkillSetupCommands(manifest) {
+export function runSkillSetupCommands(manifest, homeDir) {
+    const rolePackageCommands = rolePackageSetupCommands(manifest.packages);
+    if (rolePackageCommands.length > 0) {
+        console.log('\n[setup] 安装角色声明的 npm packages...');
+        runSetupCommandGroup('role packages', rolePackageCommands);
+    }
     for (const [vendorName, vendor] of Object.entries(manifest.vendors)) {
         if (vendor.setup && vendor.setup.length > 0) {
             console.log(`\n[setup] 执行 ${vendorName} 的安装前置命令...`);
-            for (const command of vendor.setup) {
-                const commandText = setupCommandText(command);
-                if (command.skipIfCommandAvailable && isSetupCommandAvailable(command.skipIfCommandAvailable)) {
-                    console.log(`[setup] 跳过 ${commandText}，已检测到 ${command.skipIfCommandAvailable}`);
-                    continue;
-                }
-                console.log(`[setup] > ${commandText}`);
-                try {
-                    execFileSync(resolveSetupCommandExecutable(command.command, command.windowsCommandShim), command.args ?? [], {
-                        shell: shouldUseShellForSetupCommand(command.command, command.windowsCommandShim),
-                        stdio: 'inherit',
-                    });
-                }
-                catch (error) {
-                    throw new Error(`[setup] ${vendorName} 安装前置命令失败: ${commandText}\n${String(error)}`);
-                }
-            }
+            runSetupCommandGroup(vendorName, vendor.setup);
         }
         for (const link of vendor.links) {
-            if (!link.setup || link.setup.length === 0)
-                continue;
-            const skillName = path.basename(link.target);
-            console.log(`\n[setup] 执行 ${vendorName}/${skillName} 的安装前置命令...`);
-            for (const command of link.setup) {
-                const commandText = setupCommandText(command);
-                if (command.skipIfCommandAvailable && isSetupCommandAvailable(command.skipIfCommandAvailable)) {
-                    console.log(`[setup] 跳过 ${commandText}，已检测到 ${command.skipIfCommandAvailable}`);
-                    continue;
+            const setupCommands = [...(link.setup ?? [])];
+            if (link.kind === 'mcp-file') {
+                if (!homeDir) {
+                    throw new Error(`[setup] ${vendorName} MCP setup requires the AIRules home directory`);
                 }
-                console.log(`[setup] > ${commandText}`);
-                try {
-                    execFileSync(resolveSetupCommandExecutable(command.command, command.windowsCommandShim), command.args ?? [], {
-                        shell: shouldUseShellForSetupCommand(command.command, command.windowsCommandShim),
-                        stdio: 'inherit',
-                    });
+                const checkoutRoot = path.resolve(homeDir, vendor.cloneDir);
+                const sourceFile = path.resolve(checkoutRoot, link.source);
+                if (!isPathInside(checkoutRoot, sourceFile)) {
+                    throw new Error(`[setup] ${vendorName} MCP catalog resolves outside its checkout: ${link.source}`);
                 }
-                catch (error) {
-                    throw new Error(`[setup] ${vendorName}/${skillName} 安装前置命令失败: ${commandText}\n${String(error)}`);
+                const stats = lstatSync(sourceFile, { throwIfNoEntry: false });
+                if (!stats?.isFile() || stats.isSymbolicLink() || !isPathInside(checkoutRoot, realpathSync(sourceFile))) {
+                    throw new Error(`[setup] ${vendorName} MCP catalog must be a plain file inside its checkout: ${link.source}`);
                 }
+                setupCommands.push(...loadMcpCatalog(sourceFile).setup);
             }
+            if (setupCommands.length === 0)
+                continue;
+            const assetName = link.kind === 'mcp-file' ? 'mcp' : path.basename(link.target);
+            console.log(`\n[setup] 执行 ${vendorName}/${assetName} 的安装前置命令...`);
+            runSetupCommandGroup(`${vendorName}/${assetName}`, setupCommands);
+        }
+    }
+}
+function runSetupCommandGroup(owner, commands) {
+    for (const command of commands) {
+        const commandText = setupCommandText(command);
+        if (command.skipIfCommandAvailable && isSetupCommandAvailable(command.skipIfCommandAvailable)) {
+            console.log(`[setup] 跳过 ${commandText}，已检测到 ${command.skipIfCommandAvailable}`);
+            continue;
+        }
+        console.log(`[setup] > ${commandText}`);
+        try {
+            execFileSync(resolveSetupCommandExecutable(command.command, command.windowsCommandShim), command.args ?? [], {
+                shell: shouldUseShellForSetupCommand(command.command, command.windowsCommandShim),
+                stdio: 'inherit',
+            });
+        }
+        catch (error) {
+            throw new Error(`[setup] ${owner} 安装前置命令失败: ${commandText}\n${String(error)}`);
         }
     }
 }
@@ -130,7 +140,7 @@ function setupCommandText(command) {
     return [command.command, ...(command.args ?? [])].join(' ');
 }
 function rememberFlattenedTarget(targets, target, source) {
-    const targetKey = path.resolve(target).toLowerCase();
+    const targetKey = canonicalPathKey(target);
     const previousSource = targets.get(targetKey);
     if (previousSource && !isSamePath(previousSource, source)) {
         throw new Error(`Flattened skill target collision "${target}": ${previousSource} conflicts with ${source}`);
@@ -138,11 +148,7 @@ function rememberFlattenedTarget(targets, target, source) {
     targets.set(targetKey, source);
 }
 export function isSamePath(p1, p2) {
-    if (!p1 || !p2)
-        return false;
-    const n1 = path.resolve(p1).toLowerCase().replace(/\\/g, '/').replace(/\/$/, '');
-    const n2 = path.resolve(p2).toLowerCase().replace(/\\/g, '/').replace(/\/$/, '');
-    return n1 === n2;
+    return areSamePaths(p1, p2);
 }
 function linkTypeForCurrentPlatform() {
     return process.platform === 'win32' ? 'junction' : 'dir';
@@ -221,11 +227,8 @@ export function syncFlattenedSkills(sourceDir, targetDir, moluoHome, options = {
                     continue;
                 }
                 const resolvedPath = realpathSync(targetPath);
-                const normalizedResolved = path.resolve(resolvedPath);
-                const normalizedMoluo = path.resolve(moluoHome);
-                const normalizedRepo = path.resolve(process.cwd()); // 仓库根目录
-                const isInternal = normalizedResolved.startsWith(normalizedMoluo)
-                    || normalizedResolved.startsWith(normalizedRepo);
+                const isInternal = isPathInside(moluoHome, resolvedPath)
+                    || isPathInside(process.cwd(), resolvedPath);
                 // 如果该链接指向我们的项目，但不在当前技能集合中，则视为过时并移除
                 if (isInternal && !currentSkills.has(entry.name)) {
                     removePath(targetPath);
@@ -267,8 +270,8 @@ export async function syncFirstPartySkillsToVendor(sourceRoot, moluoHome, role =
             const nameKey = name.toLowerCase();
             const previousSource = seenSkillNames.get(nameKey);
             if (previousSource
-                && path.resolve(previousSource.source) !== path.resolve(source)
-                && path.resolve(previousSource.root) === path.resolve(sourceSkillsDir)) {
+                && !isSamePath(previousSource.source, source)
+                && isSamePath(previousSource.root, sourceSkillsDir)) {
                 throw new Error(`First-party skill name collision "${name}": ${previousSource.source} conflicts with ${source}`);
             }
             seenSkillNames.set(nameKey, { name, source, root: sourceSkillsDir });
@@ -276,13 +279,13 @@ export async function syncFirstPartySkillsToVendor(sourceRoot, moluoHome, role =
     }
     const skillSources = [...seenSkillNames.values()].map(({ name, source }) => ({ name, source }));
     const currentSkillNames = new Set(skillSources.map(skill => skill.name));
-    const normalizedSourceSkillRoots = sourceSkillRoots.map(sourceSkillsDir => path.resolve(sourceSkillsDir));
+    const normalizedSourceSkillRoots = sourceSkillRoots.map(canonicalPath);
     const normalizedManagedSkillRoots = existsSync(rolesRoot)
         ? readdirSync(rolesRoot, { withFileTypes: true })
             .filter(entry => entry.isDirectory())
             .map(entry => path.join(rolesRoot, entry.name, 'skills'))
             .filter(existsSync)
-            .map(skillRoot => path.resolve(skillRoot))
+            .map(canonicalPath)
         : normalizedSourceSkillRoots;
     for (const entry of readdirSync(vendorSkillsDir, { withFileTypes: true })) {
         const targetPath = path.join(vendorSkillsDir, entry.name);
@@ -293,8 +296,8 @@ export async function syncFirstPartySkillsToVendor(sourceRoot, moluoHome, role =
             removePath(targetPath);
             continue;
         }
-        const resolvedPath = path.resolve(realpathSync(targetPath));
-        if (normalizedManagedSkillRoots.some(sourceSkillsDir => resolvedPath.startsWith(sourceSkillsDir)) && !currentSkillNames.has(entry.name)) {
+        const resolvedPath = realpathSync(targetPath);
+        if (normalizedManagedSkillRoots.some(sourceSkillsDir => isPathInside(sourceSkillsDir, resolvedPath)) && !currentSkillNames.has(entry.name)) {
             removePath(targetPath);
         }
     }
@@ -370,26 +373,72 @@ function escapeTomlString(value) {
 function tomlKey(key) {
     return /^[\w-]+$/u.test(key) ? key : `"${escapeTomlString(key)}"`;
 }
-function readRoleMcpServers(moluoHome, role) {
-    if (!role)
-        return undefined;
-    const sourceFile = path.join(moluoHome, 'roles', requireRoleName(role), 'mcp', 'mcp.json');
-    if (!existsSync(sourceFile))
-        return undefined;
+function readMcpServerFile(sourceFile) {
     const stats = lstatSync(sourceFile);
     if (!stats.isFile() || stats.isSymbolicLink())
-        throw new Error(`Role MCP source must be a plain file: ${sourceFile}`);
+        throw new Error(`MCP source must be a plain file: ${sourceFile}`);
     const raw = readFileSync(sourceFile, 'utf8').trim();
     if (!raw)
-        return undefined;
+        return {};
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch (error) {
-        throw new Error(`Role MCP source is invalid JSON: ${sourceFile}`, { cause: error });
+        throw new Error(`MCP source is invalid JSON: ${sourceFile}`, { cause: error });
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new Error(`MCP source must contain an "mcpServers" object: ${sourceFile}`);
+    const servers = parsed.mcpServers;
+    if (servers === undefined)
+        return {};
+    if (servers === null || typeof servers !== 'object' || Array.isArray(servers))
+        throw new Error(`MCP source must contain an "mcpServers" object: ${sourceFile}`);
+    const serverRecord = servers;
+    validateMcpServerNames(serverRecord, sourceFile);
+    return serverRecord;
+}
+function readVendorMcpServers(moluoHome) {
+    const root = path.join(moluoHome, 'vendor', 'mcps');
+    if (!existsSync(root))
+        return {};
+    const servers = Object.create(null);
+    const sources = new Map();
+    function visit(directory) {
+        const stats = lstatSync(directory);
+        if (!stats.isDirectory() || stats.isSymbolicLink())
+            throw new Error(`Managed MCP path must be a plain directory: ${directory}`);
+        for (const entry of readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+            const entryPath = path.join(directory, entry.name);
+            if (entry.isSymbolicLink())
+                throw new Error(`Managed MCP path must not be a symbolic link: ${entryPath}`);
+            if (entry.isDirectory()) {
+                visit(entryPath);
+            }
+            else if (entry.isFile() && entry.name === 'mcp.json') {
+                const fileServers = readMcpServerFile(entryPath);
+                for (const [name, server] of Object.entries(fileServers)) {
+                    const previous = sources.get(name);
+                    if (previous) {
+                        throw new Error(`Duplicate shared MCP server "${name}": ${previous} conflicts with ${entryPath}`);
+                    }
+                    servers[name] = server;
+                    sources.set(name, entryPath);
+                }
+            }
+        }
     }
-    return parsed.mcpServers && Object.keys(parsed.mcpServers).length > 0 ? parsed.mcpServers : undefined;
+    visit(root);
+    return servers;
+}
+export function readInstalledMcpServers(moluoHome, role) {
+    const servers = readVendorMcpServers(moluoHome);
+    if (role) {
+        const roleSource = path.join(moluoHome, 'roles', requireRoleName(role), 'mcp', 'mcp.json');
+        if (existsSync(roleSource))
+            Object.assign(servers, readMcpServerFile(roleSource));
+    }
+    return Object.keys(servers).length > 0 ? servers : undefined;
 }
 function readHostConfigForMerge(targetFile) {
     if (existsSync(targetFile) && lstatSync(targetFile).isSymbolicLink()) {
@@ -398,7 +447,7 @@ function readHostConfigForMerge(targetFile) {
     }
     return existsSync(targetFile) ? readFileSync(targetFile, 'utf8').replace(/^\uFEFF/u, '') : '';
 }
-function applyMcpServerProjection(servers, mcp) {
+export function applyMcpServerProjection(servers, mcp) {
     const { serverCommandFormat, serverDefaults, serverOverrides } = mcp;
     if (!serverDefaults && !serverOverrides && serverCommandFormat !== 'command-array')
         return servers;
@@ -416,7 +465,7 @@ function applyMcpServerProjection(servers, mcp) {
     }));
 }
 function projectMcpToHost(moluoHome, role, mcpHome, mcp) {
-    const servers = readRoleMcpServers(moluoHome, role);
+    const servers = readInstalledMcpServers(moluoHome, role);
     if (!servers)
         return;
     const projectedServers = applyMcpServerProjection(servers, mcp);
@@ -444,11 +493,7 @@ function projectMcpToHost(moluoHome, role, mcpHome, mcp) {
     }
     const previous = readHostConfigForMerge(targetFile);
     const cleaned = previous.replace(/\n*# >>> AIRULES MCP >>>[\s\S]*?(?:# <<< AIRULES MCP <<<|$)\n*/gu, '\n').trimEnd();
-    const serversKeyPattern = mcp.serversKey.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
-    const userDeclared = new Set();
-    const tablePattern = new RegExp(`^\\s*\\[${serversKeyPattern}\\.(?:"([^"]+)"|([\\w-]+))\\]`, 'gmu');
-    for (const match of cleaned.matchAll(tablePattern))
-        userDeclared.add(match[1] ?? match[2]);
+    const userDeclared = readTomlMcpServerNames(cleaned, mcp.serversKey);
     const lines = [];
     for (const [name, value] of Object.entries(projectedServers)) {
         if (userDeclared.has(name))
@@ -475,6 +520,43 @@ function projectMcpToHost(moluoHome, role, mcpHome, mcp) {
     const block = `# >>> AIRULES MCP >>>\n${lines.join('\n')}# <<< AIRULES MCP <<<\n`;
     writeFileSync(targetFile, cleaned ? `${cleaned}\n\n${block}` : block, 'utf8');
 }
+function decodeTomlBasicKey(value) {
+    const escapePattern = /\\(?:([btnfr"\\])|u([\dA-Fa-f]{4})|U([\dA-Fa-f]{8}))/gu;
+    let valid = true;
+    const decoded = value.replace(escapePattern, (_match, simple, shortHex, longHex) => {
+        if (simple) {
+            return {
+                'b': '\b',
+                't': '\t',
+                'n': '\n',
+                'f': '\f',
+                'r': '\r',
+                '"': '"',
+                '\\': '\\',
+            }[simple] ?? simple;
+        }
+        const codePoint = Number.parseInt(shortHex ?? longHex ?? '', 16);
+        if (codePoint > 0x10FFFF || (codePoint >= 0xD800 && codePoint <= 0xDFFF)) {
+            valid = false;
+            return '';
+        }
+        return String.fromCodePoint(codePoint);
+    });
+    return valid ? decoded : undefined;
+}
+export function readTomlMcpServerNames(content, serversKey) {
+    const names = new Set();
+    const escapedServersKey = serversKey.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+    const basicKey = '"((?:[^"\\\\\\r\\n]|\\\\(?:[btnfr"\\\\]|u[\\dA-Fa-f]{4}|U[\\dA-Fa-f]{8}))*)"';
+    const literalKey = `'([^'\\r\\n]*)'`;
+    const tablePattern = new RegExp(`^\\s*\\[${escapedServersKey}\\.(?:${basicKey}|${literalKey}|([\\w-]+))\\]\\s*(?:#.*)?$`, 'gmu');
+    for (const match of content.matchAll(tablePattern)) {
+        const name = match[1] === undefined ? (match[2] ?? match[3]) : decodeTomlBasicKey(match[1]);
+        if (name !== undefined)
+            names.add(name);
+    }
+    return names;
+}
 export function projectToHost({ userHome, moluoHome, hostHome, customSkillsDirName = 'skills', excludedSkills = [], projectSkills = true, role = DEFAULT_ROLE, mcpHome = hostHome, mcp, }) {
     if (projectSkills) {
         projectSkillsToHost(userHome, moluoHome, path.join(hostHome, customSkillsDirName), { excludedSkills });
@@ -493,8 +575,7 @@ export function projectHostById(host, userHome, moluoHome, role = DEFAULT_ROLE)
     const { hostHome, projectSkills, skillsDirName, excludedSkills, mcpHome, mcp } = resolveHostPaths(config, userHome);
     const hostHomePath = path.resolve(hostHome);
     const hasHostHome = existsSync(hostHomePath);
-    const hasMcpHome = Boolean(role
-        && mcp
+    const hasMcpHome = Boolean(mcp
         && existsSync(path.resolve(mcpHome))
         && (mcp.requireHostHome !== true || hasHostHome));
     if (!hasHostHome && !hasMcpHome) {

package/dist/scripts/lib/mcp-catalog.d.ts

@@ -0,0 +1,7 @@
+import type { SetupCommand } from './vendors.js';
+export interface McpCatalog {
+    servers: Record<string, Record<string, unknown>>;
+    setup: SetupCommand[];
+}
+export declare function validateMcpServerNames(servers: Record<string, unknown>, sourceFile: string): void;
+export declare function loadMcpCatalog(sourceFile: string): McpCatalog;

package/dist/scripts/lib/mcp-catalog.js

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+const reservedServerNames = new Set(['__proto__', 'constructor', 'prototype']);
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function parseSetupCommand(value, location) {
+    if (!isRecord(value) || typeof value.command !== 'string' || value.command.length === 0) {
+        throw new Error(`MCP setup command must declare a non-empty command: ${location}`);
+    }
+    if (value.args !== undefined && (!Array.isArray(value.args) || !value.args.every(argument => typeof argument === 'string'))) {
+        throw new Error(`MCP setup command args must be a string array: ${location}`);
+    }
+    if (value.windowsCommandShim !== undefined && typeof value.windowsCommandShim !== 'boolean') {
+        throw new Error(`MCP setup windowsCommandShim must be boolean: ${location}`);
+    }
+    if (value.skipIfCommandAvailable !== undefined && typeof value.skipIfCommandAvailable !== 'string') {
+        throw new Error(`MCP setup skipIfCommandAvailable must be a string: ${location}`);
+    }
+    return {
+        command: value.command,
+        ...(value.args === undefined ? {} : { args: value.args }),
+        ...(value.windowsCommandShim === undefined ? {} : { windowsCommandShim: value.windowsCommandShim }),
+        ...(value.skipIfCommandAvailable === undefined ? {} : { skipIfCommandAvailable: value.skipIfCommandAvailable }),
+    };
+}
+export function validateMcpServerNames(servers, sourceFile) {
+    for (const name of Object.keys(servers)) {
+        if (name.length === 0) {
+            throw new Error(`MCP server name must be non-empty: ${sourceFile}#${name}`);
+        }
+        if (reservedServerNames.has(name)) {
+            throw new Error(`MCP server name is reserved: ${sourceFile}#${name}`);
+        }
+    }
+}
+export function loadMcpCatalog(sourceFile) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(sourceFile, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`MCP catalog is invalid JSON: ${sourceFile}`, { cause: error });
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.mcps)) {
+        throw new Error(`MCP catalog must contain an "mcps" object: ${sourceFile}`);
+    }
+    validateMcpServerNames(parsed.mcps, sourceFile);
+    const servers = Object.create(null);
+    const setup = [];
+    for (const [name, value] of Object.entries(parsed.mcps)) {
+        if (!name || !isRecord(value) || !isRecord(value.mcp)) {
+            throw new Error(`MCP catalog entry must contain an "mcp" object: ${sourceFile}#${name}`);
+        }
+        if (value.setup !== undefined && !Array.isArray(value.setup)) {
+            throw new Error(`MCP catalog entry setup must be an array: ${sourceFile}#${name}`);
+        }
+        servers[name] = value.mcp;
+        for (const [index, command] of (value.setup ?? []).entries()) {
+            setup.push(parseSetupCommand(command, `${sourceFile}#${name}.setup[${index}]`));
+        }
+    }
+    return { servers, setup };
+}

package/dist/scripts/lib/role-packages.d.ts

@@ -0,0 +1,36 @@
+interface PackageJson {
+    dependencies?: Record<string, string>;
+    name?: string;
+    optionalDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    private?: boolean;
+    publishConfig?: {
+        access?: string;
+    };
+    scripts?: Record<string, string>;
+    version?: string;
+}
+export interface ResolvedRolePackage {
+    directory: string;
+    name: string;
+    packageJson: PackageJson;
+    relativePath: string;
+    version: string;
+}
+export interface RolePackageWorkspace {
+    packages: ResolvedRolePackage[];
+    role: string;
+    roleRoot: string;
+    version: string;
+}
+export interface RoleReleaseTag {
+    role: string;
+    version: string;
+}
+export declare function parseRoleReleaseTag(tagValue: string): RoleReleaseTag;
+export declare function npmDistTag(version: string): string;
+export declare function compareSemver(left: string, right: string): number;
+export declare function loadRolePackageWorkspace(repoRoot: string, roleValue: unknown): Promise<RolePackageWorkspace>;
+export declare function discoverRolePackageWorkspaces(repoRoot: string): Promise<RolePackageWorkspace[]>;
+export declare function requireReleaseMatchesWorkspace(release: RoleReleaseTag, workspace: RolePackageWorkspace): void;
+export {};