@cleocode/mcp-server 0.86.0

package/dist/lib/error-handler.js

@@ -0,0 +1,277 @@
+/**
+ * Error handler for CLEO CLI operations
+ *
+ * @task T2913
+ * @epic T2908
+ *
+ * Processes CLI errors, generates contextual fix commands,
+ * and formats error responses with recovery suggestions.
+ */
+import { ExitCode, ErrorCategory, getErrorMapping, isError, isRetryable, isNonRecoverable, generateFixCommand, generateSuggestions, } from './exit-codes.js';
+/**
+ * Handle CLI error and format response
+ */
+export function handleCLIError(exitCode, context) {
+    const mapping = getErrorMapping(exitCode);
+    // Extract context from stderr/stdout
+    const errorContext = extractErrorContext(exitCode, context);
+    // Generate fix command
+    const fix = generateFixCommand(exitCode, errorContext);
+    // Generate alternatives
+    const alternatives = generateSuggestions(exitCode, errorContext);
+    return {
+        code: mapping.code,
+        name: mapping.name,
+        exitCode,
+        message: formatErrorMessage(exitCode, context, errorContext),
+        description: mapping.description,
+        category: mapping.category,
+        severity: mapping.severity,
+        retryable: mapping.retryable,
+        fix,
+        alternatives,
+        context: errorContext,
+        documentation: mapping.documentation,
+    };
+}
+/**
+ * Extract error context from CLI output
+ */
+function extractErrorContext(exitCode, context) {
+    const extracted = {
+        command: context.command,
+        ...context.details,
+    };
+    // Parse stderr for context clues
+    if (context.stderr) {
+        const stderr = context.stderr;
+        // Extract task IDs
+        const taskIdMatch = stderr.match(/T(\d+)/);
+        if (taskIdMatch) {
+            extracted.taskId = taskIdMatch[0];
+        }
+        // Extract parent IDs
+        const parentMatch = stderr.match(/parent[:\s]+T(\d+)/i);
+        if (parentMatch) {
+            extracted.parentId = parentMatch[0].match(/T\d+/)?.[0] || '';
+        }
+        // Extract epic IDs
+        const epicMatch = stderr.match(/epic[:\s]+T(\d+)/i);
+        if (epicMatch) {
+            extracted.epicId = epicMatch[0].match(/T\d+/)?.[0] || '';
+        }
+        // Extract session IDs
+        const sessionMatch = stderr.match(/session[:\s]+([a-z0-9_]+)/i);
+        if (sessionMatch) {
+            extracted.sessionId = sessionMatch[1];
+        }
+        // Extract gate names
+        const gateMatch = stderr.match(/gate[:\s]+(\w+)/i);
+        if (gateMatch) {
+            extracted.gateName = gateMatch[1];
+        }
+        // Extract agent names
+        const agentMatch = stderr.match(/agent[:\s]+(\w+)/i);
+        if (agentMatch) {
+            extracted.agentName = agentMatch[1];
+        }
+        // Extract resource names
+        const resourceMatch = stderr.match(/resource[:\s]+([^\s]+)/i);
+        if (resourceMatch) {
+            extracted.resource = resourceMatch[1];
+        }
+        // Extract query strings
+        const queryMatch = stderr.match(/query[:\s]+"([^"]+)"/i);
+        if (queryMatch) {
+            extracted.query = queryMatch[1];
+        }
+        // Extract percentages
+        const percentageMatch = stderr.match(/(\d+)%/);
+        if (percentageMatch) {
+            extracted.percentage = percentageMatch[1];
+        }
+        // Extract violations
+        const violationsMatch = stderr.match(/violations?[:\s]+(.+)/i);
+        if (violationsMatch) {
+            extracted.violations = violationsMatch[1];
+        }
+        // Extract stages
+        const stageMatch = stderr.match(/stage[:\s]+(\w+)/i);
+        if (stageMatch) {
+            extracted.stage = stageMatch[1];
+        }
+        // Extract missing stages
+        const missingStagesMatch = stderr.match(/missing[:\s]+(.+)/i);
+        if (missingStagesMatch) {
+            extracted.missingStages = missingStagesMatch[1];
+        }
+    }
+    return extracted;
+}
+/**
+ * Format error message with context
+ */
+function formatErrorMessage(exitCode, context, extracted) {
+    const mapping = getErrorMapping(exitCode);
+    // Start with base description
+    let message = mapping.description;
+    // Add context-specific details
+    if (context.stderr) {
+        // Try to extract first line of error message
+        const firstLine = context.stderr.split('\n')[0].trim();
+        if (firstLine && firstLine.length < 200) {
+            message = firstLine;
+        }
+    }
+    return message;
+}
+/**
+ * Check if error is recoverable (can be fixed by user action)
+ */
+export function isRecoverable(exitCode) {
+    const mapping = getErrorMapping(exitCode);
+    // Context errors require agent action, not user action
+    if (mapping.category === ErrorCategory.CONTEXT) {
+        return false;
+    }
+    // Verification locked errors cannot be recovered automatically
+    if (exitCode === ExitCode.E_VERIFICATION_LOCKED) {
+        return false;
+    }
+    // Cascade failures need manual intervention
+    if (exitCode === ExitCode.E_CASCADE_FAILED) {
+        return false;
+    }
+    // Session close blocked needs tasks to be completed first
+    if (exitCode === ExitCode.E_SESSION_CLOSE_BLOCKED) {
+        return false;
+    }
+    // Circular validation needs different agent
+    if (exitCode === ExitCode.E_CIRCULAR_VALIDATION) {
+        return false;
+    }
+    // Invalid lifecycle transitions cannot be recovered
+    if (exitCode === ExitCode.E_LIFECYCLE_TRANSITION_INVALID) {
+        return false;
+    }
+    // File errors and dependency errors are not recoverable
+    if (exitCode === ExitCode.E_FILE_ERROR ||
+        exitCode === ExitCode.E_DEPENDENCY_ERROR) {
+        return false;
+    }
+    // Circular references are not recoverable
+    if (exitCode === ExitCode.E_CIRCULAR_REFERENCE) {
+        return false;
+    }
+    // Most other errors are recoverable by user action
+    return isError(exitCode);
+}
+/**
+ * Format error for MCP response
+ */
+export function formatErrorForMCP(error) {
+    return {
+        success: false,
+        error: {
+            code: error.code,
+            exitCode: error.exitCode,
+            message: error.message,
+            details: {
+                description: error.description,
+                category: error.category,
+                severity: error.severity,
+                retryable: error.retryable,
+                recoverable: isRecoverable(error.exitCode),
+                context: error.context,
+            },
+            fix: error.fix,
+            alternatives: error.alternatives,
+        },
+    };
+}
+/**
+ * Add error context from operation details
+ */
+export function addErrorContext(context, additionalDetails) {
+    return {
+        ...context,
+        details: {
+            ...context.details,
+            ...additionalDetails,
+        },
+    };
+}
+/**
+ * Create error context from operation
+ */
+export function createErrorContext(command, args, stderr, stdout, details) {
+    return {
+        command,
+        args,
+        stderr,
+        stdout,
+        details,
+    };
+}
+/**
+ * Default maximum retry attempts
+ *
+ * @task T3142
+ */
+const DEFAULT_MAX_ATTEMPTS = 3;
+/**
+ * Retry an operation with exponential backoff for retryable errors.
+ *
+ * Per MCP-SERVER-SPECIFICATION Section 9.1:
+ * - Exit codes 7, 20-22, 60-63 support retry with exponential backoff
+ * - Max 3 attempts by default
+ * - Backoff: 2^attempt seconds
+ * - Tracks retry count in response metadata
+ *
+ * Non-recoverable errors (Section 9.2) are never retried and
+ * immediately rethrown.
+ *
+ * @task T3142
+ */
+export async function retryOperation(fn, maxAttempts = DEFAULT_MAX_ATTEMPTS) {
+    const retriedExitCodes = [];
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const result = await fn();
+            return {
+                result,
+                attempts: attempt,
+                retriedExitCodes,
+            };
+        }
+        catch (error) {
+            const exitCode = error?.exitCode;
+            // Non-recoverable errors must never be retried (Section 9.2)
+            if (exitCode !== undefined && isNonRecoverable(exitCode)) {
+                throw error;
+            }
+            // Non-retryable errors or last attempt: throw immediately
+            if (exitCode === undefined ||
+                !isRetryable(exitCode) ||
+                attempt === maxAttempts) {
+                throw error;
+            }
+            // Track the retried exit code
+            retriedExitCodes.push(exitCode);
+            // Exponential backoff: 2^attempt seconds
+            const delayMs = Math.pow(2, attempt) * 1000;
+            await sleep(delayMs);
+        }
+    }
+    // Should never reach here, but TypeScript requires it
+    throw new Error('retryOperation: exhausted all attempts');
+}
+/**
+ * Sleep for a given number of milliseconds
+ *
+ * @task T3142
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/lib/error-handler.js.map

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

package/dist/lib/executor.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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
+ */
+/**
+ * Execution options
+ */
+export interface ExecutorOptions {
+    /** CLI command domain */
+    domain: string;
+    /** Operation to perform */
+    operation: string;
+    /** Positional arguments */
+    args?: Array<string | number>;
+    /** Named flags/options */
+    flags?: Record<string, unknown>;
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Maximum retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Session ID to bind to */
+    sessionId?: string;
+    /** Working directory (default: process.cwd()) */
+    cwd?: string;
+    /** Custom command to execute instead of building from domain/operation */
+    customCommand?: string;
+}
+/**
+ * Execution result
+ */
+export interface ExecutorResult<T = unknown> {
+    /** Whether execution succeeded */
+    success: boolean;
+    /** Parsed JSON data (if success=true) */
+    data?: T;
+    /** Error details (if success=false) */
+    error?: {
+        code: string;
+        exitCode?: number;
+        message: string;
+        details?: unknown;
+        fix?: string;
+        alternatives?: Array<{
+            action: string;
+            command: string;
+        }>;
+    };
+    /** Exit code from CLI */
+    exitCode: number;
+    /** Raw stdout */
+    stdout: string;
+    /** Raw stderr */
+    stderr: string;
+    /** Execution duration in milliseconds */
+    duration: number;
+}
+/**
+ * CLI executor class
+ */
+export declare class CLIExecutor {
+    private cliPath;
+    private defaultTimeout;
+    private defaultMaxRetries;
+    constructor(cliPath: string, defaultTimeout?: number, defaultMaxRetries?: number);
+    /**
+     * Execute CLI command with retry logic
+     */
+    execute<T = unknown>(options: ExecutorOptions): Promise<ExecutorResult<T>>;
+    /**
+     * Execute CLI command once (no retry)
+     */
+    private executeOnce;
+    /**
+     * Build CLI command string
+     */
+    private buildCommand;
+    /**
+     * Build environment variables
+     */
+    private buildEnvironment;
+    /**
+     * Parse command output
+     */
+    private parseOutput;
+    /**
+     * Determine if error is retryable
+     */
+    private shouldRetry;
+    /**
+     * Sleep for specified milliseconds
+     */
+    private sleep;
+    /**
+     * Get CLI version
+     */
+    getVersion(): Promise<string>;
+    /**
+     * Test CLI connection
+     */
+    testConnection(): Promise<boolean>;
+}
+/**
+ * Create executor instance from config
+ */
+export declare function createExecutor(cliPath: string, timeout?: number, maxRetries?: number): CLIExecutor;
+//# sourceMappingURL=executor.d.ts.map

package/dist/lib/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/lib/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IAEf,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAElB,2BAA2B;IAC3B,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAE9B,0BAA0B;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhC,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,4BAA4B;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,iDAAiD;IACjD,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IAEjB,yCAAyC;IACzC,IAAI,CAAC,EAAE,CAAC,CAAC;IAET,uCAAuC;IACvC,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,YAAY,CAAC,EAAE,KAAK,CAAC;YACnB,MAAM,EAAE,MAAM,CAAC;YACf,OAAO,EAAE,MAAM,CAAC;SACjB,CAAC,CAAC;KACJ,CAAC;IAEF,yBAAyB;IACzB,QAAQ,EAAE,MAAM,CAAC;IAEjB,iBAAiB;IACjB,MAAM,EAAE,MAAM,CAAC;IAEf,iBAAiB;IACjB,MAAM,EAAE,MAAM,CAAC;IAEf,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,WAAW;IAEpB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,iBAAiB;gBAFjB,OAAO,EAAE,MAAM,EACf,cAAc,GAAE,MAAc,EAC9B,iBAAiB,GAAE,MAAU;IAGvC;;OAEG;IACG,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IA6BhF;;OAEG;YACW,WAAW;IAuEzB;;OAEG;IACH,OAAO,CAAC,YAAY;IAgBpB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;OAEG;IACH,OAAO,CAAC,WAAW;IA4KnB;;OAEG;IACH,OAAO,CAAC,WAAW;IAUnB;;OAEG;IACH,OAAO,CAAC,KAAK;IAIb;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IA+BnC;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;CAQzC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB,WAAW,CAEb"}