@cleocode/cleo 2026.2.5

package/dist/mcp/domains/skills.js

@@ -0,0 +1,691 @@
+/**
+ * Skills Domain Handler
+ *
+ * Implements skills operations for CLEO MCP server:
+ * - Query (10): list, show, search, dispatch, verify, dependencies,
+ *               catalog.protocols, catalog.profiles, catalog.resources, catalog.info
+ * - Mutate (6): install, uninstall, enable, disable, configure, refresh
+ *
+ * Uses @cleocode/ct-skills for skill metadata and dispatch simulation.
+ * Uses @cleocode/caamp catalog namespace for protocol/profile/resource access.
+ *
+ * @task T4387
+ * @task T4704
+ */
+import { createGatewayMeta } from '../lib/gateway-meta.js';
+import { listSkills, getSkill, getCoreSkills, getSkillsByCategory, getSkillDependencies, resolveDependencyTree, getDispatchMatrix, validateSkillFrontmatter, validateAll, manifest as skillManifest, version as ctSkillsVersion, } from '@cleocode/ct-skills';
+import { catalog } from '@cleocode/caamp';
+/**
+ * Convert a SkillEntry to a SkillSummary for list responses
+ */
+function toSkillSummary(entry) {
+    return {
+        name: entry.name,
+        version: entry.version,
+        description: entry.description,
+        category: entry.category,
+        core: entry.core,
+        tier: entry.tier,
+        status: 'active',
+        protocol: entry.protocol,
+    };
+}
+/**
+ * Convert a SkillEntry to a SkillDetail for show responses
+ */
+function toSkillDetail(entry) {
+    // Find matching manifest skill for capabilities/constraints
+    const manifestSkill = skillManifest?.skills?.find((s) => s.name === entry.name);
+    return {
+        ...toSkillSummary(entry),
+        path: entry.path,
+        references: entry.references,
+        dependencies: entry.dependencies,
+        sharedResources: entry.sharedResources,
+        compatibility: entry.compatibility,
+        license: entry.license,
+        metadata: entry.metadata,
+        capabilities: manifestSkill
+            ? {
+                inputs: manifestSkill.capabilities.inputs,
+                outputs: manifestSkill.capabilities.outputs,
+                dispatch_triggers: manifestSkill.capabilities.dispatch_triggers,
+                compatible_subagent_types: manifestSkill.capabilities.compatible_subagent_types,
+                chains_to: manifestSkill.capabilities.chains_to,
+                dispatch_keywords: manifestSkill.capabilities.dispatch_keywords,
+            }
+            : undefined,
+        constraints: manifestSkill
+            ? {
+                max_context_tokens: manifestSkill.constraints.max_context_tokens,
+                requires_session: manifestSkill.constraints.requires_session,
+                requires_epic: manifestSkill.constraints.requires_epic,
+            }
+            : undefined,
+    };
+}
+/**
+ * Skills domain handler implementation
+ */
+export class SkillsHandler {
+    executor;
+    constructor(executor) {
+        this.executor = executor;
+    }
+    /**
+     * Query operations (read-only)
+     */
+    async query(operation, params) {
+        const startTime = Date.now();
+        try {
+            switch (operation) {
+                case 'list':
+                    return this.queryList(params, startTime);
+                case 'show':
+                    return this.queryShow(params, startTime);
+                case 'find':
+                    return this.querySearch(params, startTime);
+                case 'dispatch':
+                    return this.queryDispatch(params, startTime);
+                case 'verify':
+                    return this.queryVerify(params, startTime);
+                case 'dependencies':
+                    return this.queryDependencies(params, startTime);
+                case 'catalog.protocols':
+                    return this.queryCatalogProtocols(startTime);
+                case 'catalog.profiles':
+                    return this.queryCatalogProfiles(startTime);
+                case 'catalog.resources':
+                    return this.queryCatalogResources(startTime);
+                case 'catalog.info':
+                    return this.queryCatalogInfo(startTime);
+                default:
+                    return this.createErrorResponse('cleo_query', 'skills', operation, 'E_INVALID_OPERATION', `Unknown query operation: ${operation}`, startTime);
+            }
+        }
+        catch (error) {
+            return this.handleError('cleo_query', 'skills', operation, error, startTime);
+        }
+    }
+    /**
+     * Mutate operations (write)
+     */
+    async mutate(operation, params) {
+        const startTime = Date.now();
+        // Mutate operations require CLI executor
+        if (!this.executor || !this.executor.isAvailable()) {
+            return this.createErrorResponse('cleo_mutate', 'skills', operation, 'E_CLI_REQUIRED', `Operation 'skills.${operation}' requires the CLEO CLI (bash). Install with: ./install.sh`, startTime);
+        }
+        try {
+            switch (operation) {
+                case 'install':
+                    return await this.mutateInstall(params, startTime);
+                case 'uninstall':
+                    return await this.mutateUninstall(params, startTime);
+                case 'enable':
+                    return await this.mutateEnable(params, startTime);
+                case 'disable':
+                    return await this.mutateDisable(params, startTime);
+                case 'configure':
+                    return await this.mutateConfigure(params, startTime);
+                case 'refresh':
+                    return await this.mutateRefresh(params, startTime);
+                default:
+                    return this.createErrorResponse('cleo_mutate', 'skills', operation, 'E_INVALID_OPERATION', `Unknown mutate operation: ${operation}`, startTime);
+            }
+        }
+        catch (error) {
+            return this.handleError('cleo_mutate', 'skills', operation, error, startTime);
+        }
+    }
+    /**
+     * Get supported operations
+     * @task T4704
+     */
+    getSupportedOperations() {
+        return {
+            query: [
+                'list', 'show', 'find', 'dispatch', 'verify', 'dependencies',
+                'catalog.protocols', 'catalog.profiles', 'catalog.resources', 'catalog.info',
+            ],
+            mutate: ['install', 'uninstall', 'enable', 'disable', 'configure', 'refresh'],
+        };
+    }
+    // ===== Query Operations =====
+    /**
+     * list - List available skills with optional filtering
+     */
+    queryList(params, startTime) {
+        let entries;
+        if (params?.category) {
+            entries = getSkillsByCategory(params.category);
+        }
+        else if (params?.core === true) {
+            entries = getCoreSkills();
+        }
+        else {
+            const names = listSkills();
+            entries = names
+                .map((name) => getSkill(name))
+                .filter((e) => e !== undefined);
+        }
+        // Apply text filter if provided
+        if (params?.filter) {
+            const filterLower = params.filter.toLowerCase();
+            entries = entries.filter((e) => e.name.toLowerCase().includes(filterLower) ||
+                e.description.toLowerCase().includes(filterLower));
+        }
+        const skills = entries.map(toSkillSummary);
+        return {
+            _meta: { ...createGatewayMeta('cleo_query', 'skills', 'list', startTime), ctSkillsVersion },
+            success: true,
+            data: skills,
+        };
+    }
+    /**
+     * show - Get detailed skill information
+     */
+    queryShow(params, startTime) {
+        if (!params?.name) {
+            return this.createErrorResponse('cleo_query', 'skills', 'show', 'E_INVALID_INPUT', 'name is required', startTime);
+        }
+        const entry = getSkill(params.name);
+        if (!entry) {
+            return this.createErrorResponse('cleo_query', 'skills', 'show', 'E_NOT_FOUND', `Skill '${params.name}' not found`, startTime);
+        }
+        return {
+            _meta: createGatewayMeta('cleo_query', 'skills', 'show', startTime),
+            success: true,
+            data: toSkillDetail(entry),
+        };
+    }
+    /**
+     * find - Find skills by query string
+     */
+    querySearch(params, startTime) {
+        if (!params?.query) {
+            return this.createErrorResponse('cleo_query', 'skills', 'find', 'E_INVALID_INPUT', 'query is required', startTime);
+        }
+        const queryLower = params.query.toLowerCase();
+        const limit = params.limit ?? 10;
+        const names = listSkills();
+        const scored = names
+            .map((name) => {
+            const entry = getSkill(name);
+            if (!entry)
+                return null;
+            let score = 0;
+            let matchReason = '';
+            // Exact name match
+            if (entry.name.toLowerCase() === queryLower) {
+                score = 100;
+                matchReason = 'exact name match';
+            }
+            // Name contains query
+            else if (entry.name.toLowerCase().includes(queryLower)) {
+                score = 80;
+                matchReason = 'name contains query';
+            }
+            // Description contains query
+            else if (entry.description.toLowerCase().includes(queryLower)) {
+                score = 60;
+                matchReason = 'description match';
+            }
+            // Protocol match
+            else if (entry.protocol?.toLowerCase().includes(queryLower)) {
+                score = 50;
+                matchReason = 'protocol match';
+            }
+            // Category match
+            else if (entry.category.toLowerCase().includes(queryLower)) {
+                score = 40;
+                matchReason = 'category match';
+            }
+            if (score === 0)
+                return null;
+            return {
+                ...toSkillSummary(entry),
+                score,
+                matchReason,
+            };
+        })
+            .filter((r) => r !== null)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+        return {
+            _meta: createGatewayMeta('cleo_query', 'skills', 'find', startTime),
+            success: true,
+            data: {
+                query: params.query,
+                results: scored,
+            },
+        };
+    }
+    /**
+     * dispatch - Simulate skill selection for a task
+     *
+     * Uses ct-skills dispatch matrix to match skills to task parameters.
+     * This is a read-only simulation - no state changes.
+     */
+    queryDispatch(params, startTime) {
+        if (!params?.taskType && !params?.labels?.length && !params?.title && !params?.description && !params?.taskId) {
+            return this.createErrorResponse('cleo_query', 'skills', 'dispatch', 'E_INVALID_INPUT', 'At least one of taskId, taskType, labels, title, or description is required', startTime);
+        }
+        const matrix = getDispatchMatrix();
+        const candidates = [];
+        // Strategy 1: Label-based dispatch
+        if (params.labels?.length) {
+            for (const label of params.labels) {
+                // Check dispatch_matrix.by_keyword for label matches
+                const normalizedLabel = label.toLowerCase();
+                for (const [keyword, skillName] of Object.entries(matrix.by_keyword)) {
+                    if (normalizedLabel.includes(keyword.toLowerCase())) {
+                        candidates.push({
+                            skill: skillName,
+                            score: 90,
+                            strategy: 'label',
+                            reason: `Label '${label}' matched keyword '${keyword}'`,
+                        });
+                    }
+                }
+            }
+        }
+        // Strategy 2: Type-based dispatch
+        if (params.taskType) {
+            const typeMatch = matrix.by_task_type[params.taskType];
+            if (typeMatch) {
+                candidates.push({
+                    skill: typeMatch,
+                    score: 85,
+                    strategy: 'type',
+                    reason: `Task type '${params.taskType}' mapped to skill`,
+                });
+            }
+        }
+        // Strategy 3: Keyword-based dispatch from title/description
+        const searchText = [params.title, params.description]
+            .filter(Boolean)
+            .join(' ')
+            .toLowerCase();
+        if (searchText) {
+            for (const [keyword, skillName] of Object.entries(matrix.by_keyword)) {
+                if (searchText.includes(keyword.toLowerCase())) {
+                    // Avoid duplicate candidates from same skill
+                    if (!candidates.some((c) => c.skill === skillName && c.strategy === 'keyword')) {
+                        candidates.push({
+                            skill: skillName,
+                            score: 70,
+                            strategy: 'keyword',
+                            reason: `Text matched dispatch keyword '${keyword}'`,
+                        });
+                    }
+                }
+            }
+        }
+        // Strategy 4: Fallback
+        if (candidates.length === 0) {
+            const fallback = matrix.by_task_type['default'] || 'ct-task-executor';
+            candidates.push({
+                skill: fallback,
+                score: 10,
+                strategy: 'fallback',
+                reason: 'No specific match found, using default executor',
+            });
+        }
+        // Sort by score descending
+        candidates.sort((a, b) => b.score - a.score);
+        const selected = candidates[0];
+        return {
+            _meta: createGatewayMeta('cleo_query', 'skills', 'dispatch', startTime),
+            success: true,
+            data: {
+                selectedSkill: selected.skill,
+                reason: selected.reason,
+                strategy: selected.strategy,
+                candidates,
+            },
+        };
+    }
+    /**
+     * verify - Validate skill frontmatter
+     */
+    queryVerify(params, startTime) {
+        if (params?.name) {
+            // Validate single skill
+            const entry = getSkill(params.name);
+            if (!entry) {
+                return this.createErrorResponse('cleo_query', 'skills', 'verify', 'E_NOT_FOUND', `Skill '${params.name}' not found`, startTime);
+            }
+            const result = validateSkillFrontmatter(params.name);
+            return {
+                _meta: createGatewayMeta('cleo_query', 'skills', 'verify', startTime),
+                success: true,
+                data: {
+                    valid: result.valid,
+                    total: 1,
+                    passed: result.valid ? 1 : 0,
+                    failed: result.valid ? 0 : 1,
+                    results: [
+                        {
+                            name: params.name,
+                            valid: result.valid,
+                            issues: result.issues,
+                        },
+                    ],
+                },
+            };
+        }
+        // Validate all skills
+        const allResults = validateAll();
+        let passed = 0;
+        let failed = 0;
+        const results = [];
+        allResults.forEach((result, name) => {
+            if (result.valid) {
+                passed++;
+            }
+            else {
+                failed++;
+            }
+            results.push({
+                name,
+                valid: result.valid,
+                issues: result.issues,
+            });
+        });
+        return {
+            _meta: createGatewayMeta('cleo_query', 'skills', 'verify', startTime),
+            success: true,
+            data: {
+                valid: failed === 0,
+                total: passed + failed,
+                passed,
+                failed,
+                results,
+            },
+        };
+    }
+    /**
+     * dependencies - Get skill dependency tree
+     */
+    queryDependencies(params, startTime) {
+        if (!params?.name) {
+            return this.createErrorResponse('cleo_query', 'skills', 'dependencies', 'E_INVALID_INPUT', 'name is required', startTime);
+        }
+        const entry = getSkill(params.name);
+        if (!entry) {
+            return this.createErrorResponse('cleo_query', 'skills', 'dependencies', 'E_NOT_FOUND', `Skill '${params.name}' not found`, startTime);
+        }
+        const directDeps = getSkillDependencies(params.name);
+        const resolvedTree = params.transitive !== false
+            ? resolveDependencyTree([params.name])
+            : directDeps;
+        // Build dependency nodes
+        const dependencies = resolvedTree
+            .filter((name) => name !== params.name)
+            .map((name) => {
+            const depEntry = getSkill(name);
+            return {
+                name,
+                version: depEntry?.version ?? 'unknown',
+                direct: directDeps.includes(name),
+                depth: directDeps.includes(name) ? 1 : 2,
+            };
+        });
+        return {
+            _meta: createGatewayMeta('cleo_query', 'skills', 'dependencies', startTime),
+            success: true,
+            data: {
+                name: params.name,
+                dependencies,
+                resolved: resolvedTree.filter((n) => n !== params.name),
+            },
+        };
+    }
+    // ===== Catalog Operations (T4704) =====
+    /**
+     * catalog.protocols - List available RCSD-IVTR protocols
+     * @task T4704
+     */
+    queryCatalogProtocols(startTime) {
+        try {
+            const protocols = catalog.listProtocols();
+            const details = protocols.map((name) => ({
+                name,
+                path: catalog.getProtocolPath(name) ?? null,
+            }));
+            return {
+                _meta: createGatewayMeta('cleo_query', 'skills', 'catalog.protocols', startTime),
+                success: true,
+                data: { protocols: details },
+            };
+        }
+        catch (error) {
+            return this.handleError('cleo_query', 'skills', 'catalog.protocols', error, startTime);
+        }
+    }
+    /**
+     * catalog.profiles - List available skill profiles
+     * @task T4704
+     */
+    queryCatalogProfiles(startTime) {
+        try {
+            const profileNames = catalog.listProfiles();
+            const profiles = profileNames.map((name) => {
+                const profile = catalog.getProfile(name);
+                return {
+                    name,
+                    description: profile?.description ?? '',
+                    extends: profile?.extends,
+                    skillCount: profile?.skills.length ?? 0,
+                    skills: profile?.skills ?? [],
+                };
+            });
+            return {
+                _meta: createGatewayMeta('cleo_query', 'skills', 'catalog.profiles', startTime),
+                success: true,
+                data: { profiles },
+            };
+        }
+        catch (error) {
+            return this.handleError('cleo_query', 'skills', 'catalog.profiles', error, startTime);
+        }
+    }
+    /**
+     * catalog.resources - List available shared resources
+     * @task T4704
+     */
+    queryCatalogResources(startTime) {
+        try {
+            const resources = catalog.listSharedResources();
+            const details = resources.map((name) => ({
+                name,
+                path: catalog.getSharedResourcePath(name) ?? null,
+            }));
+            return {
+                _meta: createGatewayMeta('cleo_query', 'skills', 'catalog.resources', startTime),
+                success: true,
+                data: { resources: details },
+            };
+        }
+        catch (error) {
+            return this.handleError('cleo_query', 'skills', 'catalog.resources', error, startTime);
+        }
+    }
+    /**
+     * catalog.info - Get catalog metadata (version, availability, library root)
+     * @task T4704
+     */
+    queryCatalogInfo(startTime) {
+        try {
+            const available = catalog.isCatalogAvailable();
+            const version = available ? catalog.getVersion() : null;
+            const libraryRoot = available ? catalog.getLibraryRoot() : null;
+            const skillCount = available ? catalog.getSkills().length : 0;
+            const protocolCount = available ? catalog.listProtocols().length : 0;
+            const profileCount = available ? catalog.listProfiles().length : 0;
+            return {
+                _meta: createGatewayMeta('cleo_query', 'skills', 'catalog.info', startTime),
+                success: true,
+                data: {
+                    available,
+                    version,
+                    libraryRoot,
+                    skillCount,
+                    protocolCount,
+                    profileCount,
+                    ctSkillsVersion,
+                },
+            };
+        }
+        catch (error) {
+            return this.handleError('cleo_query', 'skills', 'catalog.info', error, startTime);
+        }
+    }
+    // ===== Mutate Operations =====
+    /**
+     * install - Install a skill
+     * CLI: cleo skill install <name> [--source <source>]
+     */
+    async mutateInstall(params, startTime) {
+        if (!params?.name) {
+            return this.createErrorResponse('cleo_mutate', 'skills', 'install', 'E_INVALID_INPUT', 'name is required', startTime);
+        }
+        const flags = { json: true };
+        if (params.source)
+            flags.source = params.source;
+        const result = await this.executor.execute({
+            domain: 'skill',
+            operation: 'install',
+            args: [params.name],
+            flags,
+        });
+        return this.wrapExecutorResult(result, 'cleo_mutate', 'skills', 'install', startTime);
+    }
+    /**
+     * uninstall - Uninstall a skill
+     * CLI: cleo skill uninstall <name> [--force]
+     */
+    async mutateUninstall(params, startTime) {
+        if (!params?.name) {
+            return this.createErrorResponse('cleo_mutate', 'skills', 'uninstall', 'E_INVALID_INPUT', 'name is required', startTime);
+        }
+        const flags = { json: true };
+        if (params.force)
+            flags.force = true;
+        const result = await this.executor.execute({
+            domain: 'skill',
+            operation: 'uninstall',
+            args: [params.name],
+            flags,
+        });
+        return this.wrapExecutorResult(result, 'cleo_mutate', 'skills', 'uninstall', startTime);
+    }
+    /**
+     * enable - Enable a skill
+     * CLI: cleo skill enable <name>
+     */
+    async mutateEnable(params, startTime) {
+        if (!params?.name) {
+            return this.createErrorResponse('cleo_mutate', 'skills', 'enable', 'E_INVALID_INPUT', 'name is required', startTime);
+        }
+        const result = await this.executor.execute({
+            domain: 'skill',
+            operation: 'enable',
+            args: [params.name],
+            flags: { json: true },
+        });
+        return this.wrapExecutorResult(result, 'cleo_mutate', 'skills', 'enable', startTime);
+    }
+    /**
+     * disable - Disable a skill
+     * CLI: cleo skill disable <name> [--reason <reason>]
+     */
+    async mutateDisable(params, startTime) {
+        if (!params?.name) {
+            return this.createErrorResponse('cleo_mutate', 'skills', 'disable', 'E_INVALID_INPUT', 'name is required', startTime);
+        }
+        const flags = { json: true };
+        if (params.reason)
+            flags.reason = params.reason;
+        const result = await this.executor.execute({
+            domain: 'skill',
+            operation: 'disable',
+            args: [params.name],
+            flags,
+        });
+        return this.wrapExecutorResult(result, 'cleo_mutate', 'skills', 'disable', startTime);
+    }
+    /**
+     * configure - Configure a skill
+     * CLI: cleo skill configure <name> --config <json>
+     */
+    async mutateConfigure(params, startTime) {
+        if (!params?.name) {
+            return this.createErrorResponse('cleo_mutate', 'skills', 'configure', 'E_INVALID_INPUT', 'name is required', startTime);
+        }
+        if (!params?.config || typeof params.config !== 'object') {
+            return this.createErrorResponse('cleo_mutate', 'skills', 'configure', 'E_INVALID_INPUT', 'config object is required', startTime);
+        }
+        const result = await this.executor.execute({
+            domain: 'skill',
+            operation: 'configure',
+            args: [params.name],
+            flags: { config: JSON.stringify(params.config), json: true },
+        });
+        return this.wrapExecutorResult(result, 'cleo_mutate', 'skills', 'configure', startTime);
+    }
+    /**
+     * refresh - Refresh skill registry cache
+     * CLI: cleo skill refresh [--force]
+     */
+    async mutateRefresh(params, startTime) {
+        const flags = { json: true };
+        if (params?.force)
+            flags.force = true;
+        const result = await this.executor.execute({
+            domain: 'skill',
+            operation: 'refresh',
+            flags,
+        });
+        return this.wrapExecutorResult(result, 'cleo_mutate', 'skills', 'refresh', startTime);
+    }
+    // ===== Helper Methods =====
+    /**
+     * Wrap executor result in DomainResponse format
+     */
+    wrapExecutorResult(result, gateway, domain, operation, startTime) {
+        if (result.success) {
+            return {
+                _meta: createGatewayMeta(gateway, domain, operation, startTime),
+                success: true,
+                data: result.data,
+            };
+        }
+        return {
+            _meta: createGatewayMeta(gateway, domain, operation, startTime),
+            success: false,
+            error: result.error,
+        };
+    }
+    /**
+     * Create error response
+     */
+    createErrorResponse(gateway, domain, operation, code, message, startTime) {
+        return {
+            _meta: createGatewayMeta(gateway, domain, operation, startTime),
+            success: false,
+            error: {
+                code,
+                message,
+            },
+        };
+    }
+    /**
+     * Handle unexpected errors
+     */
+    handleError(gateway, domain, operation, error, startTime) {
+        return this.createErrorResponse(gateway, domain, operation, 'E_INTERNAL_ERROR', error instanceof Error ? error.message : String(error), startTime);
+    }
+}
+//# sourceMappingURL=skills.js.map