@cleocode/mcp-server 0.86.0

package/dist/lib/executor.js

@@ -0,0 +1,362 @@
+/**
+ * CLI Executor Wrapper
+ *
+ * Executes CLEO CLI commands safely with timeout handling, retry logic,
+ * and proper error parsing. Captures stdout, stderr, and exit codes.
+ *
+ * @task T2914
+ */
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { buildCLICommand } from './command-builder.js';
+import { isRetryableError } from '../types/index.js';
+const execAsync = promisify(exec);
+/**
+ * CLI executor class
+ */
+export class CLIExecutor {
+    cliPath;
+    defaultTimeout;
+    defaultMaxRetries;
+    constructor(cliPath, defaultTimeout = 30000, defaultMaxRetries = 3) {
+        this.cliPath = cliPath;
+        this.defaultTimeout = defaultTimeout;
+        this.defaultMaxRetries = defaultMaxRetries;
+    }
+    /**
+     * Execute CLI command with retry logic
+     */
+    async execute(options) {
+        const maxRetries = options.maxRetries ?? this.defaultMaxRetries;
+        let lastError = null;
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            const result = await this.executeOnce(options, attempt);
+            // Success - return immediately
+            if (result.success) {
+                return result;
+            }
+            // Non-retryable error - return immediately
+            if (!this.shouldRetry(result.exitCode, attempt, maxRetries)) {
+                return result;
+            }
+            // Store error for potential final return
+            lastError = result;
+            // Exponential backoff: 2^attempt seconds
+            const backoffMs = Math.pow(2, attempt) * 1000;
+            await this.sleep(backoffMs);
+        }
+        // All retries exhausted
+        return lastError;
+    }
+    /**
+     * Execute CLI command once (no retry)
+     */
+    async executeOnce(options, attempt) {
+        const startTime = Date.now();
+        const timeout = options.timeout ?? this.defaultTimeout;
+        try {
+            // Build command
+            const command = this.buildCommand(options);
+            // Prepare environment
+            const env = this.buildEnvironment(options);
+            // Execute with timeout
+            const { stdout, stderr } = await execAsync(command, {
+                timeout,
+                cwd: options.cwd || process.cwd(),
+                env: { ...process.env, ...env },
+                maxBuffer: 10 * 1024 * 1024, // 10MB buffer
+            });
+            const duration = Date.now() - startTime;
+            // Parse output
+            return this.parseOutput(stdout, stderr, 0, duration);
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            // Handle exec errors (exit code, timeout, etc.)
+            if (error.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
+                return {
+                    success: false,
+                    error: {
+                        code: 'E_OUTPUT_TOO_LARGE',
+                        message: 'Command output exceeded buffer size',
+                        fix: 'Add --limit flag to reduce output size',
+                    },
+                    exitCode: 1,
+                    stdout: error.stdout || '',
+                    stderr: error.stderr || '',
+                    duration,
+                };
+            }
+            if (error.killed) {
+                return {
+                    success: false,
+                    error: {
+                        code: 'E_TIMEOUT',
+                        message: `Command timed out after ${timeout}ms`,
+                        fix: `Increase timeout or optimize query`,
+                    },
+                    exitCode: 124,
+                    stdout: error.stdout || '',
+                    stderr: error.stderr || '',
+                    duration,
+                };
+            }
+            // Command executed but returned non-zero exit code
+            const exitCode = error.code || 1;
+            return this.parseOutput(error.stdout || '', error.stderr || '', exitCode, duration);
+        }
+    }
+    /**
+     * Build CLI command string
+     */
+    buildCommand(options) {
+        // If customCommand is provided, use it directly
+        if (options.customCommand) {
+            return options.customCommand;
+        }
+        // Otherwise build from domain/operation
+        return buildCLICommand(this.cliPath, options.domain, options.operation, options.args || [], options.flags || {});
+    }
+    /**
+     * Build environment variables
+     */
+    buildEnvironment(options) {
+        const env = {};
+        // Bind to session if specified
+        if (options.sessionId) {
+            env.CLEO_SESSION = options.sessionId;
+        }
+        return env;
+    }
+    /**
+     * Parse command output
+     */
+    parseOutput(stdout, stderr, exitCode, duration) {
+        // Try to parse stdout as JSON, fall back to stderr if stdout is empty
+        // Some CLI commands (e.g., orchestrator context) output JSON to stderr
+        // with non-zero exit codes that still contain success:true
+        const rawOutput = stdout.trim() || stderr.trim();
+        try {
+            const trimmed = rawOutput;
+            if (!trimmed) {
+                // Empty output with zero exit = success
+                if (exitCode === 0) {
+                    return {
+                        success: true,
+                        data: undefined,
+                        exitCode,
+                        stdout,
+                        stderr,
+                        duration,
+                    };
+                }
+                // Empty output with non-zero exit = error
+                return {
+                    success: false,
+                    error: {
+                        code: 'E_UNKNOWN',
+                        exitCode,
+                        message: stderr.trim() || 'Command failed with no output',
+                    },
+                    exitCode,
+                    stdout,
+                    stderr,
+                    duration,
+                };
+            }
+            const parsed = JSON.parse(trimmed);
+            // CLI returned structured JSON response
+            if (typeof parsed === 'object' && parsed !== null) {
+                // Check for success field
+                if ('success' in parsed) {
+                    if (parsed.success === true) {
+                        // Extract payload data from CLI response.
+                        // CLEO CLI returns payload fields directly on the response object
+                        // (e.g., "task", "tasks", "session", "sessionId") rather than
+                        // wrapping them in a "data" field. Extract by removing envelope fields.
+                        let data;
+                        if (parsed.data !== undefined) {
+                            data = parsed.data;
+                        }
+                        else {
+                            // CLEO CLI returns payload fields at the top level rather than
+                            // wrapping in a "data" field. Look for well-known primary payload
+                            // fields and unwrap them, falling back to the full parsed object.
+                            const primaryPayloadFields = [
+                                'task', 'tasks', 'session', 'sessions', 'matches',
+                                'result', 'focus', 'entries', 'stages', 'summary',
+                            ];
+                            const found = primaryPayloadFields.find((f) => parsed[f] !== undefined);
+                            if (found) {
+                                data = parsed[found];
+                            }
+                            else {
+                                // No recognized primary field - strip standard envelope
+                                // and return remaining fields as data
+                                const envelope = new Set([
+                                    '$schema', '_meta', 'success', 'error', 'warnings',
+                                ]);
+                                const payload = {};
+                                for (const [key, value] of Object.entries(parsed)) {
+                                    if (!envelope.has(key)) {
+                                        payload[key] = value;
+                                    }
+                                }
+                                const payloadKeys = Object.keys(payload);
+                                if (payloadKeys.length === 1) {
+                                    data = payload[payloadKeys[0]];
+                                }
+                                else if (payloadKeys.length === 0) {
+                                    data = parsed;
+                                }
+                                else {
+                                    data = payload;
+                                }
+                            }
+                        }
+                        return {
+                            success: true,
+                            data,
+                            exitCode,
+                            stdout,
+                            stderr,
+                            duration,
+                        };
+                    }
+                    // Structured error response
+                    return {
+                        success: false,
+                        error: {
+                            code: parsed.error?.code || 'E_UNKNOWN',
+                            exitCode: parsed.error?.exitCode || exitCode,
+                            message: parsed.error?.message || 'Command failed',
+                            details: parsed.error?.details,
+                            fix: parsed.error?.fix,
+                            alternatives: parsed.error?.alternatives,
+                        },
+                        exitCode,
+                        stdout,
+                        stderr,
+                        duration,
+                    };
+                }
+                // JSON without success field - treat as data
+                return {
+                    success: exitCode === 0,
+                    data: parsed,
+                    exitCode,
+                    stdout,
+                    stderr,
+                    duration,
+                };
+            }
+        }
+        catch (parseError) {
+            // Not valid JSON - treat as plain text
+            if (exitCode === 0) {
+                // Success with non-JSON output
+                return {
+                    success: true,
+                    data: stdout.trim(),
+                    exitCode,
+                    stdout,
+                    stderr,
+                    duration,
+                };
+            }
+            // Error with non-JSON output
+            return {
+                success: false,
+                error: {
+                    code: 'E_UNKNOWN',
+                    exitCode,
+                    message: stderr.trim() || stdout.trim() || 'Command failed',
+                },
+                exitCode,
+                stdout,
+                stderr,
+                duration,
+            };
+        }
+        // Shouldn't reach here, but TypeScript needs it
+        return {
+            success: false,
+            error: {
+                code: 'E_UNKNOWN',
+                exitCode,
+                message: 'Unexpected execution result',
+            },
+            exitCode,
+            stdout,
+            stderr,
+            duration,
+        };
+    }
+    /**
+     * Determine if error is retryable
+     */
+    shouldRetry(exitCode, attempt, maxRetries) {
+        // Max retries exhausted
+        if (attempt >= maxRetries) {
+            return false;
+        }
+        // Check if error code is retryable
+        return isRetryableError(exitCode);
+    }
+    /**
+     * Sleep for specified milliseconds
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Get CLI version
+     */
+    async getVersion() {
+        const result = await this.execute({
+            domain: 'system',
+            operation: 'version',
+            customCommand: `${this.cliPath} version --json`,
+            maxRetries: 1,
+        });
+        if (result.success) {
+            // Try data field first (already parsed by execute)
+            if (result.data && typeof result.data === 'object' && 'version' in result.data) {
+                return result.data.version;
+            }
+            // Fallback: parse version from raw stdout JSON
+            try {
+                const parsed = JSON.parse(result.stdout.trim());
+                if (parsed.version) {
+                    return parsed.version;
+                }
+                if (parsed.data?.version) {
+                    return parsed.data.version;
+                }
+            }
+            catch (e) {
+                // Not valid JSON, continue to error
+            }
+        }
+        throw new Error(`Failed to get CLI version: ${result.error?.message || 'Unknown error'}`);
+    }
+    /**
+     * Test CLI connection
+     */
+    async testConnection() {
+        try {
+            await this.getVersion();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/**
+ * Create executor instance from config
+ */
+export function createExecutor(cliPath, timeout, maxRetries) {
+    return new CLIExecutor(cliPath, timeout, maxRetries);
+}
+//# sourceMappingURL=executor.js.map

package/dist/lib/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/lib/executor.ts"],"names":[],"mappings":"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"}

package/dist/lib/exit-codes.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Exit code mapping for CLEO CLI operations
+ *
+ * @task T2913
+ * @epic T2908
+ *
+ * Maps all CLEO exit codes (1-100+) to error metadata with automatic
+ * fix command generation and contextual suggestions.
+ *
+ * Reference: lib/exit-codes.sh, lib/protocol-validation.sh
+ */
+/**
+ * Exit code enumeration (complete mapping 0-100+)
+ */
+export declare enum ExitCode {
+    SUCCESS = 0,
+    E_GENERAL_ERROR = 1,
+    E_INVALID_INPUT = 2,
+    E_FILE_ERROR = 3,
+    E_NOT_FOUND = 4,
+    E_DEPENDENCY_ERROR = 5,
+    E_VALIDATION_ERROR = 6,
+    E_LOCK_TIMEOUT = 7,
+    E_CONFIG_ERROR = 8,
+    E_PARENT_NOT_FOUND = 10,
+    E_DEPTH_EXCEEDED = 11,
+    E_SIBLING_LIMIT = 12,
+    E_INVALID_PARENT_TYPE = 13,
+    E_CIRCULAR_REFERENCE = 14,
+    E_ORPHAN_DETECTED = 15,
+    E_HAS_CHILDREN = 16,
+    E_TASK_COMPLETED = 17,
+    E_CASCADE_FAILED = 18,
+    E_HAS_DEPENDENTS = 19,
+    E_CHECKSUM_MISMATCH = 20,
+    E_CONCURRENT_MODIFICATION = 21,
+    E_ID_COLLISION = 22,
+    E_SESSION_EXISTS = 30,
+    E_SESSION_NOT_FOUND = 31,
+    E_SCOPE_CONFLICT = 32,
+    E_SCOPE_INVALID = 33,
+    E_TASK_NOT_IN_SCOPE = 34,
+    E_TASK_CLAIMED = 35,
+    E_SESSION_REQUIRED = 36,
+    E_SESSION_CLOSE_BLOCKED = 37,
+    E_FOCUS_REQUIRED = 38,
+    E_NOTES_REQUIRED = 39,
+    E_VERIFICATION_INIT_FAILED = 40,
+    E_GATE_UPDATE_FAILED = 41,
+    E_INVALID_GATE = 42,
+    E_INVALID_AGENT = 43,
+    E_MAX_ROUNDS_EXCEEDED = 44,
+    E_GATE_DEPENDENCY = 45,
+    E_VERIFICATION_LOCKED = 46,
+    E_ROUND_MISMATCH = 47,
+    E_CONTEXT_WARNING = 50,
+    E_CONTEXT_CAUTION = 51,
+    E_CONTEXT_CRITICAL = 52,
+    E_CONTEXT_EMERGENCY = 53,
+    E_CONTEXT_STALE = 54,
+    E_PROTOCOL_RESEARCH = 60,
+    E_PROTOCOL_CONSENSUS = 61,
+    E_PROTOCOL_SPECIFICATION = 62,
+    E_PROTOCOL_DECOMPOSITION = 63,
+    E_PROTOCOL_IMPLEMENTATION = 64,
+    E_PROTOCOL_CONTRIBUTION = 65,
+    E_PROTOCOL_RELEASE = 66,
+    E_PROTOCOL_GENERIC = 67,
+    E_PROTOCOL_VALIDATION = 68,
+    E_TESTS_SKIPPED = 69,
+    E_COVERAGE_INSUFFICIENT = 70,
+    E_NEXUS_NOT_INITIALIZED = 71,
+    E_NEXUS_PROJECT_NOT_FOUND = 72,
+    E_NEXUS_PERMISSION_DENIED = 73,
+    E_NEXUS_INVALID_SYNTAX = 74,
+    E_NEXUS_SYNC_FAILED = 75,
+    E_NEXUS_REGISTRY_CORRUPT = 76,
+    E_NEXUS_PROJECT_EXISTS = 77,
+    E_NEXUS_QUERY_FAILED = 78,
+    E_NEXUS_GRAPH_ERROR = 79,
+    E_LIFECYCLE_GATE_FAILED = 80,
+    E_AUDIT_MISSING = 81,
+    E_CIRCULAR_VALIDATION = 82,
+    E_LIFECYCLE_TRANSITION_INVALID = 83,
+    E_PROVENANCE_REQUIRED = 84,
+    E_NO_DATA = 100,
+    E_ALREADY_EXISTS = 101,
+    E_NO_CHANGE = 102
+}
+/**
+ * Error severity levels
+ */
+export declare enum ErrorSeverity {
+    INFO = "info",
+    WARNING = "warning",
+    ERROR = "error",
+    CRITICAL = "critical"
+}
+/**
+ * Error category for grouping
+ */
+export declare enum ErrorCategory {
+    GENERAL = "general",
+    HIERARCHY = "hierarchy",
+    CONCURRENCY = "concurrency",
+    SESSION = "session",
+    VERIFICATION = "verification",
+    CONTEXT = "context",
+    PROTOCOL = "protocol",
+    NEXUS = "nexus",
+    LIFECYCLE = "lifecycle",
+    SPECIAL = "special"
+}
+/**
+ * Alternative action suggestion
+ */
+export interface ErrorAlternative {
+    action: string;
+    command: string;
+}
+/**
+ * Complete error metadata mapping
+ */
+export interface ErrorMapping {
+    code: string;
+    name: string;
+    description: string;
+    category: ErrorCategory;
+    severity: ErrorSeverity;
+    retryable: boolean;
+    fixTemplate?: string;
+    alternatives?: ErrorAlternative[];
+    documentation?: string;
+}
+/**
+ * Complete exit code to error mapping
+ */
+export declare const ERROR_MAP: Record<number, ErrorMapping>;
+/**
+ * Get error mapping for exit code
+ */
+export declare function getErrorMapping(exitCode: number): ErrorMapping;
+/**
+ * Check if exit code represents an error
+ */
+export declare function isError(exitCode: number): boolean;
+/**
+ * Check if exit code is retryable
+ */
+export declare function isRetryable(exitCode: number): boolean;
+/**
+ * Check if exit code represents success
+ */
+export declare function isSuccess(exitCode: number): boolean;
+/**
+ * Generate fix command from template
+ */
+export declare function generateFixCommand(exitCode: number, context: Record<string, string>): string | undefined;
+/**
+ * Generate suggestions from alternatives
+ */
+export declare function generateSuggestions(exitCode: number, context: Record<string, string>): ErrorAlternative[];
+/**
+ * Exit codes that support automatic retry with exponential backoff.
+ * Per MCP-SERVER-SPECIFICATION Section 9.1.
+ *
+ * @task T3142
+ */
+export declare const RETRYABLE_EXIT_CODES: ReadonlySet<number>;
+/**
+ * Exit codes that require human intervention and must NEVER be retried.
+ * Per MCP-SERVER-SPECIFICATION Section 9.2.
+ *
+ * @task T3142
+ */
+export declare const NON_RECOVERABLE_EXIT_CODES: ReadonlySet<number>;
+/**
+ * Check if an exit code represents a non-recoverable error
+ * requiring human intervention. These must NEVER be retried.
+ *
+ * @task T3142
+ */
+export declare function isNonRecoverable(exitCode: number): boolean;
+/**
+ * Check if an exit code represents a recoverable error
+ * @param exitCode The exit code to check
+ * @returns true if the error is retryable
+ */
+export declare function isRecoverable(exitCode: number): boolean;
+//# sourceMappingURL=exit-codes.d.ts.map

package/dist/lib/exit-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.d.ts","sourceRoot":"","sources":["../../src/lib/exit-codes.ts"],"names":[],"mappings":"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"}