moluoxixi-ai-rules 0.2.11 → 0.2.13

package/dist/scripts/lib/role-contract.js

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import { parseDocument, visit } from 'yaml';
+import { requireRoleName } from './role-assets.js';
+const installationFields = ['hosts', 'packages', 'assets', 'distribution', 'entrypoints', 'role_vendor', 'role_vendor_position'];
+const metadataFields = ['schema_version', 'role_id', 'role_version', 'status', 'canonical_root', 'description', 'extends_roles', 'provides', 'installation'];
+function requireRecord(value, location) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new TypeError(`${location} must be an object`);
+    return value;
+}
+function requireFields(record, allowed, location) {
+    for (const field of Object.keys(record)) {
+        if (!allowed.includes(field))
+            throw new Error(`${location} has unsupported field "${field}"`);
+    }
+}
+export function requireRoleInheritance(value, location, schemaVersion = 1) {
+    if (!Array.isArray(value) || !value.every(role => typeof role === 'string'))
+        throw new TypeError(`${location} must be a string array`);
+    if (schemaVersion < 2 && value.length > 1)
+        throw new Error(`${location} supports at most one parent role (single inheritance); use schema_version: 2 for multiple parents`);
+    const seen = new Set();
+    for (const role of value) {
+        requireRoleName(role);
+        const key = role.toLowerCase();
+        if (seen.has(key))
+            throw new Error(`${location} declares duplicate parent role "${role}"`);
+        seen.add(key);
+    }
+    return [...value];
+}
+export function readRoleContract(contractPath) {
+    const location = `Role contract "${contractPath}"`;
+    const document = parseDocument(fs.readFileSync(contractPath, 'utf8'), {
+        merge: false,
+        prettyErrors: true,
+        strict: true,
+        uniqueKeys: true,
+    });
+    if (document.errors.length > 0)
+        throw new Error(`${location} is invalid: ${document.errors.map(error => error.message).join('; ')}`);
+    visit(document, {
+        Alias() {
+            throw new Error(`${location} must not use YAML aliases`);
+        },
+    });
+    const record = requireRecord(document.toJS({ maxAliasCount: 0 }), `${location} YAML mapping`);
+    const schemaVersion = record.schema_version === undefined ? 1 : record.schema_version;
+    if (schemaVersion !== 1 && schemaVersion !== 2)
+        throw new Error(`${location} schema_version must be 1 or 2`);
+    let provides = record;
+    let installation = record;
+    if (schemaVersion === 2) {
+        requireFields(record, metadataFields, location);
+        requireRoleName(record.role_id);
+        provides = requireRecord(record.provides, `${location} provides`);
+        requireFields(provides, ['capabilities'], `${location} provides`);
+        installation = requireRecord(record.installation === undefined ? {} : record.installation, `${location} installation`);
+        requireFields(installation, installationFields, `${location} installation`);
+        if (!Array.isArray(provides.capabilities))
+            throw new TypeError(`${location} provides.capabilities must be a list`);
+        if (installation.assets !== undefined) {
+            const assets = requireRecord(installation.assets, `${location} installation.assets`);
+            for (const [name, root] of Object.entries(assets)) {
+                if (typeof root !== 'string' || root.length === 0)
+                    throw new TypeError(`${location} installation.assets.${name} must be a non-empty relative path`);
+                if (/^(?:[\\/]|[A-Za-z]:)/u.test(root) || root.replaceAll('\\', '/').split('/').includes('..'))
+                    throw new Error(`${location} installation.assets.${name} must stay inside the role`);
+            }
+        }
+    }
+    else if (record.provides !== undefined || record.installation !== undefined) {
+        throw new Error(`${location} provides/installation require schema_version: 2`);
+    }
+    const roleVendorPosition = schemaVersion === 2 ? installation.role_vendor_position : installation.role_vendor_position ?? installation.roleVendorPosition;
+    if (roleVendorPosition !== undefined && roleVendorPosition !== 'before' && roleVendorPosition !== 'after')
+        throw new Error(`${location} field "role_vendor_position" must be "before" or "after"`);
+    return {
+        path: contractPath,
+        schemaVersion,
+        roleId: record.role_id,
+        canonicalRoot: record.canonical_root,
+        capabilities: provides.capabilities,
+        extendsRoles: requireRoleInheritance(schemaVersion === 2
+            ? record.extends_roles === undefined ? [] : record.extends_roles
+            : record.extends_roles ?? record.extendsRoles ?? [], `${location} field "extends_roles"`, schemaVersion),
+        hosts: installation.hosts,
+        packages: installation.packages,
+        assets: installation.assets,
+        distribution: installation.distribution,
+        entrypoints: installation.entrypoints,
+        roleVendor: installation.role_vendor ?? installation.roleVendor,
+        roleVendorPosition,
+    };
+}

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

@@ -1,15 +1,11 @@
+import type { RoleInheritanceEntry, RolePaths } from './types/roles.js';
+export { requireRoleInheritance } from './role-contract.js';
+export type { RolePaths } from './types/roles.js';
 export declare const DEFAULT_ROLE = "";
 export declare const COMMON_ROLE = "";
-export interface RolePaths {
-    role: string;
-    roleRoot: string;
-    roleManifest: string;
-    constantsDir?: string;
-    constantsFile?: string;
-}
 export declare function requireRolePaths(repoRoot: string, roleValue: unknown): RolePaths;
 export declare function roleOverlayOrder(repoRoot: string, roleValue?: unknown): Promise<string[]>;
-export declare function requireRoleInheritance(value: unknown, location: string): string[];
+export declare function resolveRoleInheritance(repoRoot: string, roleValue?: unknown): Promise<RoleInheritanceEntry[]>;
 export declare function resolveRoleManifestPath(repoRoot: string, roleValue: unknown, options?: {
     preferDist?: boolean;
 }): string;

package/dist/scripts/lib/roles.js

@@ -1,9 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { parseDocument } from 'yaml';
 import { isPathInside } from './canonical-path.js';
 import { requireRoleName } from './role-assets.js';
+import { readRoleContract, requireRoleInheritance } from './role-contract.js';
+export { requireRoleInheritance } from './role-contract.js';
 export const DEFAULT_ROLE = '';
 export const COMMON_ROLE = '';
 export function requireRolePaths(repoRoot, roleValue) {
@@ -58,33 +59,44 @@ export function requireRolePaths(repoRoot, roleValue) {
     return { role, roleRoot, roleManifest, constantsDir, constantsFile };
 }
 export async function roleOverlayOrder(repoRoot, roleValue = DEFAULT_ROLE) {
+    return (await resolveRoleInheritance(repoRoot, roleValue)).map(entry => entry.role);
+}
+export async function resolveRoleInheritance(repoRoot, roleValue = DEFAULT_ROLE) {
     if (roleValue === '') {
         return [];
     }
     const role = requireRoleName(roleValue);
     const orderedRoles = [];
     const visitingRoles = new Set();
-    let roleName = role;
-    while (roleName !== undefined) {
-        requireRolePaths(repoRoot, roleName);
+    const visitedRoles = new Set();
+    async function visit(roleName, inheritancePath) {
         if (visitingRoles.has(roleName)) {
-            throw new Error(`AIRules role inheritance cycle detected at "${roleName}"`);
+            throw new Error(`AIRules role inheritance cycle detected: ${inheritancePath.join(' → ')}`);
         }
+        if (visitedRoles.has(roleName))
+            return;
+        const { roleManifest: manifestPath } = requireRolePaths(repoRoot, roleName);
         visitingRoles.add(roleName);
-        orderedRoles.push(roleName);
-        const parents = await loadRoleExtendsRoles(repoRoot, roleName);
-        roleName = parents[0];
-    }
-    return orderedRoles.reverse();
-}
-export function requireRoleInheritance(value, location) {
-    if (!Array.isArray(value) || !value.every(roleName => typeof roleName === 'string')) {
-        throw new TypeError(`${location} must be a string array`);
-    }
-    if (value.length > 1) {
-        throw new Error(`${location} supports at most one parent role (single inheritance)`);
+        const contract = path.basename(manifestPath).toLowerCase() === 'role.yaml' ? readRoleContract(manifestPath) : undefined;
+        if (contract?.roleId !== undefined && contract.roleId !== roleName)
+            throw new Error(`Role contract "${manifestPath}" role_id must equal "${roleName}" (${inheritancePath.join(' → ')})`);
+        if (contract?.canonicalRoot !== undefined && contract.canonicalRoot !== `roles/${roleName}`)
+            throw new Error(`Role contract "${manifestPath}" canonical_root must equal roles/${roleName} (${inheritancePath.join(' → ')})`);
+        const parents = contract?.extendsRoles ?? await loadLegacyRoleExtendsRoles(manifestPath);
+        for (const parent of parents) {
+            try {
+                await visit(parent, [...inheritancePath, parent]);
+            }
+            catch (error) {
+                throw new Error(`${String(error)} (inheritance: ${[...inheritancePath, parent].join(' → ')})`, { cause: error });
+            }
+        }
+        visitingRoles.delete(roleName);
+        visitedRoles.add(roleName);
+        orderedRoles.push({ role: roleName, manifestPath, inheritancePath, contract });
     }
-    return value;
+    await visit(role, [role]);
+    return orderedRoles;
 }
 export function resolveRoleManifestPath(repoRoot, roleValue, options = {}) {
     if (roleValue === '') {
@@ -134,30 +146,11 @@ function resolveManifestCandidate(repoRoot, requestedRoleRoot, manifestPath) {
     requireInsideRoot(roleRoot, resolvedManifest, 'role manifest', 'role root');
     return resolvedManifest;
 }
-async function loadRoleExtendsRoles(repoRoot, role) {
-    const manifestPath = resolveRoleManifestPath(repoRoot, role);
-    if (path.basename(manifestPath).toLowerCase() === 'role.yaml') {
-        const document = parseDocument(fs.readFileSync(manifestPath, 'utf8'), {
-            merge: false,
-            prettyErrors: true,
-            strict: true,
-            uniqueKeys: true,
-        });
-        if (document.errors.length > 0) {
-            throw new Error(`Role contract "${manifestPath}" is invalid: ${document.errors.map(error => error.message).join('; ')}`);
-        }
-        const value = document.toJS({ maxAliasCount: 0 });
-        if (!value || typeof value !== 'object' || Array.isArray(value)) {
-            throw new TypeError(`Role contract "${manifestPath}" must be a YAML mapping`);
-        }
-        const record = value;
-        const extendsRoles = record.extends_roles ?? record.extendsRoles ?? [];
-        return requireRoleInheritance(extendsRoles, `roles/${role}/role.yaml field "extends_roles"`);
-    }
+async function loadLegacyRoleExtendsRoles(manifestPath) {
     const manifestUrl = pathToFileURL(path.resolve(manifestPath)).href;
     const module = await import(manifestUrl);
     const extendsRoles = module.extendsRoles ?? module.default?.extendsRoles ?? [];
-    return requireRoleInheritance(extendsRoles, `roles/${role}/constants/skills.ts export "extendsRoles"`);
+    return requireRoleInheritance(extendsRoles, `Role manifest "${manifestPath}" export "extendsRoles"`);
 }
 function requireInsideRoot(root, target, field, rootLabel) {
     if (!isPathInside(root, target)) {

package/dist/scripts/lib/tool.js

@@ -53,7 +53,6 @@ async function syncVendorsIfNeeded(paths, skipVendors, manifest) {
         for (const vendor of Object.values(manifest.vendors)) {
             ensureVendorRepo(paths.moluoHome, vendor);
         }
-        runSkillSetupCommands(manifest, paths.moluoHome);
     }
     else {
         for (const vendor of Object.values(manifest.vendors)) {
@@ -72,13 +71,15 @@ async function syncVendorStaging(paths, skipVendors, manifest) {
         moluoHome: paths.moluoHome,
         repoRoot: paths.repoRoot,
     };
-    ensureInstallRoot(installPaths);
     await syncVendorsIfNeeded(paths, skipVendors, manifest);
     await rebuildVendorAssets({
         homeDir: paths.moluoHome,
         role: paths.role,
         manifestPath: paths.manifestPath,
+        manifest,
+        beforeCommit: skipVendors ? undefined : () => runSkillSetupCommands(manifest, paths.moluoHome),
     });
+    ensureInstallRoot(installPaths);
     ensureGlobalSkillLink(installPaths);
 }
 export async function syncToHosts(options) {

package/dist/scripts/lib/types/capabilities.d.ts

@@ -8,8 +8,16 @@ export interface CapabilityDefinition {
 export interface CapabilitySelection {
     definition: CapabilityDefinition;
     name: string;
+    origin?: string;
 }
 export interface ComposeCapabilitiesOptions {
     roleVendor: VendorRepo;
     roleVendorPosition?: 'before' | 'after';
+    capabilityOrigins?: Record<string, string>;
+    roleOrigin?: string;
+}
+export interface CapabilityVendorEntry {
+    vendor: VendorRepo;
+    origin: string;
+    projectionOrigins?: string[][];
 }

package/dist/scripts/lib/types/manifest.d.ts

@@ -70,16 +70,8 @@ export interface VendorManifest {
     packages?: RolePackageConfig[];
     version: number;
     vendors: Record<string, Vendor>;
-}
-export interface RoleContract {
-    path: string;
-    value: Record<string, unknown>;
-}
-export interface RoleContractData {
-    hosts?: unknown;
-    packages?: unknown;
-    capabilities?: unknown;
-    extendsRoles?: unknown;
-    roleVendor?: unknown;
-    roleVendorPosition?: 'before' | 'after';
+    origins?: Record<string, {
+        vendor: string[];
+        links: string[][];
+    }>;
 }

package/dist/scripts/lib/types/mcp.d.ts

@@ -0,0 +1,13 @@
+import type { SetupCommand } from './manifest.js';
+export interface McpCatalog {
+    servers: Record<string, Record<string, unknown>>;
+    serverSetup: Record<string, SetupCommand[]>;
+    setup: SetupCommand[];
+}
+export interface McpServerDefinition {
+    server: unknown;
+    setup: SetupCommand[];
+}
+export interface McpServerOwner extends McpServerDefinition {
+    owner: string;
+}

package/dist/scripts/lib/types/mcp.js

@@ -0,0 +1 @@
+export {};

package/dist/scripts/lib/types/roles.d.ts

@@ -0,0 +1,29 @@
+export interface RolePaths {
+    role: string;
+    roleRoot: string;
+    roleManifest: string;
+    constantsDir?: string;
+    constantsFile?: string;
+}
+/** Normalized fields; installation values always belong to this declaration. */
+export interface RoleContractData {
+    path: string;
+    schemaVersion: 1 | 2;
+    roleId?: unknown;
+    canonicalRoot?: unknown;
+    capabilities?: unknown;
+    extendsRoles: string[];
+    hosts?: unknown;
+    packages?: unknown;
+    assets?: unknown;
+    distribution?: unknown;
+    entrypoints?: unknown;
+    roleVendor?: unknown;
+    roleVendorPosition?: 'before' | 'after';
+}
+export interface RoleInheritanceEntry {
+    role: string;
+    manifestPath: string;
+    inheritancePath: string[];
+    contract?: RoleContractData;
+}

package/dist/scripts/lib/types/roles.js

@@ -0,0 +1 @@
+export {};

package/dist/scripts/lib/types/vendor-staging.d.ts

@@ -0,0 +1,51 @@
+import type { SetupCommand, VendorLink, VendorManifest } from './manifest.js';
+export interface VendorAssetInventory {
+    role: string;
+    roleRoot?: string;
+    skills: string[];
+}
+export interface RebuildVendorAssetsOptions {
+    homeDir: string;
+    role: string;
+    manifestPath: string;
+    manifest?: VendorManifest;
+    beforeCommit?: () => void | Promise<void>;
+}
+export interface PlannedAsset {
+    vendorId: string;
+    kind: VendorLink['kind'];
+    source: string;
+    target: string;
+    setup: SetupCommand[];
+    origin: string;
+}
+export interface VendorStagingPlan {
+    assets: PlannedAsset[];
+    roleSource?: string;
+    roleVendorId?: string;
+    roleMcpPath?: string;
+    roleSetup?: SetupCommand[];
+    roleOrigin?: string;
+}
+export interface MaterializedPlan {
+    buildRoot: string;
+    stagingRoot: string;
+    roleStagingRoot?: string;
+}
+export type SourceKind = 'file' | 'directory';
+export interface CanonicalRoleAssetRoots {
+    skills: string;
+    mcp: string;
+}
+export interface ManagedEntryCommit {
+    current: string;
+    backup: string;
+    movedCurrent: boolean;
+    installedNext: boolean;
+}
+export interface ManagedEntrySpec {
+    current: string;
+    next: string;
+    backup: string;
+    preserveRoot?: boolean;
+}

package/dist/scripts/lib/types/vendor-staging.js

@@ -0,0 +1 @@
+export {};

package/dist/scripts/lib/vendor-staging.d.ts

@@ -1,12 +1,4 @@
-export interface VendorAssetInventory {
-    role: string;
-    roleRoot?: string;
-    skills: string[];
-}
-export interface RebuildVendorAssetsOptions {
-    homeDir: string;
-    role: string;
-    manifestPath: string;
-}
+import type { RebuildVendorAssetsOptions, VendorAssetInventory } from './types/vendor-staging.js';
+export type { RebuildVendorAssetsOptions, VendorAssetInventory } from './types/vendor-staging.js';
 export declare function cleanupEmptyVendorSkillDirectories(homeDir: string): void;
 export declare function rebuildVendorAssets(options: RebuildVendorAssetsOptions): Promise<VendorAssetInventory>;