mcp-ai-agent-guidelines/dist/tools/shared/errors.js

A comprehensive Model Context Protocol server providing advanced tools, resources, and prompts for implementing AI agent best practices

/**
 * Centralized error handling utilities with typed errors for improved debugging and resilience
 */
import { logger } from "./logger.js";
/**
 * Base class for all operational errors in the application
 */
export class OperationError extends Error {
    code;
    context;
    timestamp;
    constructor(message, code, context) {
        super(message);
        this.name = "OperationError";
        this.code = code;
        this.context = context;
        this.timestamp = new Date();
        // Maintains proper stack trace for where our error was thrown (only available on V8)
        if (Error.captureStackTrace) {
            Error.captureStackTrace(this, OperationError);
        }
    }
}
/**
 * Validation error for input validation failures
 */
export class ValidationError extends OperationError {
    constructor(message, context) {
        super(message, "VALIDATION_ERROR", context);
        this.name = "ValidationError";
    }
}
/**
 * Configuration error for invalid or missing configuration
 */
export class ConfigurationError extends OperationError {
    constructor(message, context) {
        super(message, "CONFIGURATION_ERROR", context);
        this.name = "ConfigurationError";
    }
}
/**
 * Session error for session-related issues
 */
export class SessionError extends OperationError {
    constructor(message, context) {
        super(message, "SESSION_ERROR", context);
        this.name = "SessionError";
    }
}
/**
 * Phase error for design phase workflow issues
 */
export class PhaseError extends OperationError {
    constructor(message, context) {
        super(message, "PHASE_ERROR", context);
        this.name = "PhaseError";
    }
}
/**
 * Generation error for artifact generation failures
 */
export class GenerationError extends OperationError {
    constructor(message, context) {
        super(message, "GENERATION_ERROR", context);
        this.name = "GenerationError";
    }
}
/**
 * Consistency error for consistency enforcement failures
 */
export class ConsistencyError extends OperationError {
    constructor(message, context) {
        super(message, "CONSISTENCY_ERROR", context);
        this.name = "ConsistencyError";
    }
}
/**
 * Centralized error reporter for consistent error handling
 */
// biome-ignore lint/complexity/noStaticOnlyClass: ErrorReporter is a utility namespace that provides static helper functions for error handling
export class ErrorReporter {
    /**
     * Report and log an error, optionally rethrowing it
     */
    static report(error, context, options) {
        const operationError = ErrorReporter.toOperationError(error, context, options?.defaultMessage);
        // Log the error
        logger.error(operationError.message, {
            code: operationError.code,
            context: operationError.context,
            stack: operationError.stack,
        });
        // Optionally rethrow
        if (options?.rethrow) {
            throw operationError;
        }
        return operationError;
    }
    /**
     * Report a non-critical error as a warning
     */
    static warn(error, context, defaultMessage) {
        const message = ErrorReporter.extractMessage(error, defaultMessage);
        logger.warn(message, {
            ...context,
            error: error instanceof Error ? error.stack : String(error),
        });
    }
    /**
     * Convert any error to an OperationError
     */
    static toOperationError(error, context, defaultMessage) {
        // If already an OperationError, merge context and return
        if (error instanceof OperationError) {
            return new OperationError(error.message, error.code, {
                ...error.context,
                ...context,
            });
        }
        // If a regular Error, convert it
        if (error instanceof Error) {
            const opError = new OperationError(error.message, "UNKNOWN_ERROR", context);
            opError.stack = error.stack;
            return opError;
        }
        // Unknown error type
        return new OperationError(defaultMessage || "An unknown error occurred", "UNKNOWN_ERROR", {
            ...context,
            originalError: String(error),
        });
    }
    /**
     * Extract error message from various error types
     */
    static extractMessage(error, defaultMessage = "Unknown error") {
        if (error instanceof Error) {
            return error.message;
        }
        if (typeof error === "string") {
            return error;
        }
        return defaultMessage;
    }
    /**
     * Create a safe error response for API returns
     */
    static createErrorResponse(error, context) {
        const operationError = ErrorReporter.toOperationError(error, context);
        return {
            success: false,
            error: {
                message: operationError.message,
                code: operationError.code,
                timestamp: operationError.timestamp.toISOString(),
                ...(operationError.context && { context: operationError.context }),
            },
        };
    }
    /**
     * Create a full error response with standard fields
     */
    static createFullErrorResponse(error, baseResponse) {
        const operationError = ErrorReporter.toOperationError(error);
        return {
            success: false,
            sessionId: baseResponse.sessionId,
            status: baseResponse.status || "error",
            message: operationError.message,
            recommendations: baseResponse.recommendations || [
                "Check request parameters and try again",
            ],
            artifacts: (baseResponse.artifacts || []),
        };
    }
}
//# sourceMappingURL=errors.js.map