@cyanheads/git-mcp-server 1.2.4 → 2.0.2

package/dist/utils/errorHandler.js

@@ -0,0 +1,237 @@
+import { BaseErrorCode, McpError } from '../types-global/errors.js';
+import { logger } from './logger.js';
+import { sanitizeInputForLogging } from './sanitization.js'; // Updated import
+/**
+ * Simple mapper that maps error types to error codes
+ */
+const ERROR_TYPE_MAPPINGS = {
+    'SyntaxError': BaseErrorCode.VALIDATION_ERROR,
+    'TypeError': BaseErrorCode.VALIDATION_ERROR,
+    'ReferenceError': BaseErrorCode.INTERNAL_ERROR,
+    'RangeError': BaseErrorCode.VALIDATION_ERROR,
+    'URIError': BaseErrorCode.VALIDATION_ERROR,
+    'EvalError': BaseErrorCode.INTERNAL_ERROR
+};
+/**
+ * Common error patterns for automatic classification
+ */
+const COMMON_ERROR_PATTERNS = [
+    // Authentication related errors
+    { pattern: /auth|unauthorized|unauthenticated|not.*logged.*in|invalid.*token|expired.*token/i, errorCode: BaseErrorCode.UNAUTHORIZED },
+    // Permission related errors
+    { pattern: /permission|forbidden|access.*denied|not.*allowed/i, errorCode: BaseErrorCode.FORBIDDEN },
+    // Not found errors
+    { pattern: /not.*found|missing|no.*such|doesn't.*exist|couldn't.*find/i, errorCode: BaseErrorCode.NOT_FOUND },
+    // Validation errors
+    { pattern: /invalid|validation|malformed|bad request|wrong format/i, errorCode: BaseErrorCode.VALIDATION_ERROR },
+    // Conflict errors
+    { pattern: /conflict|already.*exists|duplicate|unique.*constraint/i, errorCode: BaseErrorCode.CONFLICT },
+    // Rate limiting
+    { pattern: /rate.*limit|too.*many.*requests|throttled/i, errorCode: BaseErrorCode.RATE_LIMITED },
+    // Timeout errors
+    { pattern: /timeout|timed.*out|deadline.*exceeded/i, errorCode: BaseErrorCode.TIMEOUT },
+    // External service errors
+    { pattern: /service.*unavailable|bad.*gateway|gateway.*timeout/i, errorCode: BaseErrorCode.SERVICE_UNAVAILABLE }
+];
+/**
+ * Get a readable name for an error
+ * @param error Error to get name for
+ * @returns User-friendly error name
+ */
+function getErrorName(error) {
+    if (error instanceof Error) {
+        return error.name || 'Error';
+    }
+    if (error === null) {
+        return 'NullError';
+    }
+    if (error === undefined) {
+        return 'UndefinedError';
+    }
+    return typeof error === 'object'
+        ? 'ObjectError'
+        : 'UnknownError';
+}
+/**
+ * Get a message from an error
+ * @param error Error to get message from
+ * @returns Error message
+ */
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (error === null) {
+        return 'Null error occurred';
+    }
+    if (error === undefined) {
+        return 'Undefined error occurred';
+    }
+    return typeof error === 'string'
+        ? error
+        : String(error);
+}
+/**
+ * Error handler utility class with various error handling methods
+ */
+export class ErrorHandler {
+    /**
+     * Determine the appropriate error code for an error based on patterns and type
+     * @param error The error to classify
+     * @returns The appropriate error code
+     */
+    static determineErrorCode(error) {
+        // If it's already an McpError, use its code
+        if (error instanceof McpError) {
+            return error.code;
+        }
+        const errorName = getErrorName(error);
+        const errorMessage = getErrorMessage(error);
+        // Check if the error type has a direct mapping
+        if (errorName in ERROR_TYPE_MAPPINGS) {
+            return ERROR_TYPE_MAPPINGS[errorName];
+        }
+        // Check for common error patterns
+        for (const pattern of COMMON_ERROR_PATTERNS) {
+            const regex = pattern.pattern instanceof RegExp
+                ? pattern.pattern
+                : new RegExp(pattern.pattern, 'i');
+            if (regex.test(errorMessage) || regex.test(errorName)) {
+                return pattern.errorCode;
+            }
+        }
+        // Default to internal error if no pattern matches
+        return BaseErrorCode.INTERNAL_ERROR;
+    }
+    /**
+     * Handle operation errors with consistent logging and transformation
+     * @param error The error that occurred
+     * @param options Error handling options
+     * @returns The transformed error
+     */
+    static handleError(error, options) {
+        const { context, operation, input, rethrow = false, errorCode: explicitErrorCode, includeStack = true, critical = false } = options;
+        // If it's already an McpError, use it directly but apply additional context
+        if (error instanceof McpError) {
+            // Add any additional context
+            if (context && Object.keys(context).length > 0) {
+                error.details = { ...error.details, ...context };
+            }
+            // Log the error with sanitized input
+            logger.error(`Error ${operation}: ${error.message}`, {
+                errorCode: error.code,
+                requestId: context?.requestId,
+                input: input ? sanitizeInputForLogging(input) : undefined,
+                stack: includeStack ? error.stack : undefined,
+                critical,
+                ...context
+            });
+            if (rethrow) {
+                throw error;
+            }
+            return error;
+        }
+        // Sanitize input for logging
+        const sanitizedInput = input ? sanitizeInputForLogging(input) : undefined;
+        // Log the error with consistent format
+        logger.error(`Error ${operation}`, {
+            error: error instanceof Error ? error.message : String(error),
+            errorType: getErrorName(error),
+            input: sanitizedInput,
+            requestId: context?.requestId,
+            stack: includeStack && error instanceof Error ? error.stack : undefined,
+            critical,
+            ...context
+        });
+        // Choose the error code (explicit > determined > default)
+        const errorCode = explicitErrorCode ||
+            ErrorHandler.determineErrorCode(error) ||
+            BaseErrorCode.INTERNAL_ERROR;
+        // Transform to appropriate error type
+        const transformedError = options.errorMapper
+            ? options.errorMapper(error)
+            : new McpError(errorCode, `Error ${operation}: ${error instanceof Error ? error.message : 'Unknown error'}`, {
+                originalError: getErrorName(error),
+                ...context
+            });
+        // Rethrow if requested
+        if (rethrow) {
+            throw transformedError;
+        }
+        return transformedError;
+    }
+    /**
+     * Map an error to a specific error type based on error message patterns
+     * @param error The error to map
+     * @param mappings Array of pattern and factory mappings
+     * @param defaultFactory Default factory function if no pattern matches
+     * @returns The mapped error
+     */
+    static mapError(error, mappings, defaultFactory) {
+        // If it's already the target type and we have a default factory to check against, return it
+        if (defaultFactory && error instanceof Error) {
+            const defaultInstance = defaultFactory(error);
+            if (error.constructor === defaultInstance.constructor) {
+                return error;
+            }
+        }
+        const errorMessage = getErrorMessage(error);
+        // Check each pattern and return the first match
+        for (const mapping of mappings) {
+            const matches = mapping.pattern instanceof RegExp
+                ? mapping.pattern.test(errorMessage)
+                : errorMessage.includes(mapping.pattern);
+            if (matches) {
+                return mapping.factory(error, mapping.additionalContext);
+            }
+        }
+        // Return default or original error
+        if (defaultFactory) {
+            return defaultFactory(error);
+        }
+        return error instanceof Error
+            ? error
+            : new Error(String(error));
+    }
+    // Removed createErrorMapper method for simplification
+    /**
+     * Format an error for consistent response structure
+     * @param error The error to format
+     * @returns Formatted error object
+     */
+    static formatError(error) {
+        if (error instanceof McpError) {
+            return {
+                code: error.code,
+                message: error.message,
+                details: error.details || {}
+            };
+        }
+        if (error instanceof Error) {
+            return {
+                code: ErrorHandler.determineErrorCode(error),
+                message: error.message,
+                details: { errorType: error.name }
+            };
+        }
+        return {
+            code: BaseErrorCode.UNKNOWN_ERROR,
+            message: String(error),
+            details: { errorType: typeof error }
+        };
+    }
+    /**
+     * Safely execute a function and handle any errors
+     * @param fn Function to execute
+     * @param options Error handling options
+     * @returns The result of the function or error
+     */
+    static async tryCatch(fn, options) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            throw ErrorHandler.handleError(error, { ...options, rethrow: true });
+        }
+    }
+}

package/dist/utils/idGenerator.js

@@ -0,0 +1,148 @@
+import { randomBytes } from 'crypto';
+import { BaseErrorCode, McpError } from '../types-global/errors.js';
+import { logger } from './logger.js';
+/**
+ * Generic ID Generator class for creating and managing unique identifiers
+ */
+export class IdGenerator {
+    // Default charset
+    static DEFAULT_CHARSET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+    // Default separator
+    static DEFAULT_SEPARATOR = '_';
+    // Default random part length
+    static DEFAULT_LENGTH = 6;
+    // Entity prefixes
+    entityPrefixes = {};
+    // Reverse mapping for prefix to entity type lookup
+    prefixToEntityType = {};
+    /**
+     * Constructor that accepts entity prefix configuration
+     * @param entityPrefixes Map of entity types to their prefixes
+     */
+    constructor(entityPrefixes = {}) {
+        this.setEntityPrefixes(entityPrefixes);
+    }
+    /**
+     * Set or update entity prefixes and rebuild the reverse lookup
+     * @param entityPrefixes Map of entity types to their prefixes
+     */
+    setEntityPrefixes(entityPrefixes) {
+        this.entityPrefixes = { ...entityPrefixes };
+        // Rebuild reverse mapping
+        this.prefixToEntityType = Object.entries(this.entityPrefixes).reduce((acc, [type, prefix]) => {
+            acc[prefix] = type;
+            acc[prefix.toLowerCase()] = type;
+            return acc;
+        }, {});
+        logger.debug('Entity prefixes updated', { entityPrefixes: this.entityPrefixes });
+    }
+    /**
+     * Get all registered entity prefixes
+     * @returns The entity prefix configuration
+     */
+    getEntityPrefixes() {
+        return { ...this.entityPrefixes };
+    }
+    /**
+     * Generates a cryptographically secure random alphanumeric string
+     * @param length The length of the random string to generate
+     * @param charset Optional custom character set
+     * @returns Random alphanumeric string
+     */
+    generateRandomString(length = IdGenerator.DEFAULT_LENGTH, charset = IdGenerator.DEFAULT_CHARSET) {
+        const bytes = randomBytes(length);
+        let result = '';
+        for (let i = 0; i < length; i++) {
+            result += charset[bytes[i] % charset.length];
+        }
+        return result;
+    }
+    /**
+     * Generates a unique ID with an optional prefix
+     * @param prefix Optional prefix to add to the ID
+     * @param options Optional generation options
+     * @returns A unique identifier string
+     */
+    generate(prefix, options = {}) {
+        const { length = IdGenerator.DEFAULT_LENGTH, separator = IdGenerator.DEFAULT_SEPARATOR, charset = IdGenerator.DEFAULT_CHARSET } = options;
+        const randomPart = this.generateRandomString(length, charset);
+        return prefix
+            ? `${prefix}${separator}${randomPart}`
+            : randomPart;
+    }
+    /**
+     * Generates a custom ID for an entity with format PREFIX_XXXXXX
+     * @param entityType The type of entity to generate an ID for
+     * @param options Optional generation options
+     * @returns A unique identifier string (e.g., "PROJ_A6B3J0")
+     * @throws {McpError} If the entity type is not registered
+     */
+    generateForEntity(entityType, options = {}) {
+        const prefix = this.entityPrefixes[entityType];
+        if (!prefix) {
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Unknown entity type: ${entityType}`);
+        }
+        return this.generate(prefix, options);
+    }
+    /**
+     * Validates if a given ID matches the expected format for an entity type
+     * @param id The ID to validate
+     * @param entityType The expected entity type
+     * @param options Optional validation options
+     * @returns boolean indicating if the ID is valid
+     */
+    isValid(id, entityType, options = {}) {
+        const prefix = this.entityPrefixes[entityType];
+        const { length = IdGenerator.DEFAULT_LENGTH, separator = IdGenerator.DEFAULT_SEPARATOR } = options;
+        if (!prefix) {
+            return false;
+        }
+        const pattern = new RegExp(`^${prefix}${separator}[A-Z0-9]{${length}}$`);
+        return pattern.test(id);
+    }
+    /**
+     * Strips the prefix from an ID
+     * @param id The ID to strip
+     * @param separator Optional custom separator
+     * @returns The ID without the prefix
+     */
+    stripPrefix(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        return id.split(separator)[1] || id;
+    }
+    /**
+     * Determines the entity type from an ID
+     * @param id The ID to get the entity type for
+     * @param separator Optional custom separator
+     * @returns The entity type
+     * @throws {McpError} If the ID format is invalid or entity type is unknown
+     */
+    getEntityType(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        const parts = id.split(separator);
+        if (parts.length !== 2 || !parts[0]) {
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Invalid ID format: ${id}. Expected format: PREFIX${separator}XXXXXX`);
+        }
+        const prefix = parts[0];
+        const entityType = this.prefixToEntityType[prefix];
+        if (!entityType) {
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Unknown entity type prefix: ${prefix}`);
+        }
+        return entityType;
+    }
+    /**
+     * Normalizes an entity ID to ensure consistent uppercase format
+     * @param id The ID to normalize
+     * @param separator Optional custom separator
+     * @returns The normalized ID in uppercase format
+     */
+    normalize(id, separator = IdGenerator.DEFAULT_SEPARATOR) {
+        const entityType = this.getEntityType(id, separator);
+        const idParts = id.split(separator);
+        return `${this.entityPrefixes[entityType]}${separator}${idParts[1].toUpperCase()}`;
+    }
+}
+// Create and export a default instance with an empty entity prefix configuration
+export const idGenerator = new IdGenerator();
+// For standalone use as a UUID generator
+export const generateUUID = () => {
+    return crypto.randomUUID();
+};

package/dist/utils/index.js

@@ -0,0 +1,11 @@
+// Re-export all utilities using wildcard exports for simplicity
+export * from './requestContext.js';
+export * from './errorHandler.js';
+export * from './idGenerator.js';
+export * from './logger.js';
+export * from './rateLimiter.js';
+export * from './sanitization.js';
+export * from './tokenCounter.js';
+export * from './jsonParser.js';
+// No need for explicit named imports/exports or default export
+// when using wildcard exports for a simple barrel file.

package/dist/utils/jsonParser.js

@@ -0,0 +1,78 @@
+import { parse as parsePartialJson, Allow as PartialJsonAllow } from 'partial-json';
+import { BaseErrorCode, McpError } from '../types-global/errors.js';
+import { logger } from './logger.js'; // Import logger
+/**
+ * Enum mirroring partial-json's Allow constants for specifying
+ * what types of partial JSON structures are permissible during parsing.
+ * Use bitwise OR to combine options (e.g., Allow.STR | Allow.OBJ).
+ */
+export const Allow = PartialJsonAllow;
+// Regex to find a <think> block at the start, capturing its content and the rest of the string
+const thinkBlockRegex = /^<think>([\s\S]*?)<\/think>\s*([\s\S]*)$/;
+/**
+ * Utility class for parsing potentially partial JSON strings.
+ * Wraps the 'partial-json' library to provide a consistent interface
+ * within the atlas-mcp-agent project.
+ * Handles optional <think>...</think> blocks at the beginning of the input.
+ */
+class JsonParser {
+    /**
+     * Parses a JSON string, potentially allowing for incomplete structures
+     * and handling optional <think> blocks at the start.
+     *
+     * @param jsonString The JSON string to parse.
+     * @param allowPartial A bitwise OR combination of 'Allow' constants specifying permissible partial types (defaults to Allow.ALL).
+     * @param context Optional RequestContext for error correlation and logging think blocks.
+     * @returns The parsed JavaScript value.
+     * @throws {McpError} Throws an McpError with BaseErrorCode.VALIDATION_ERROR if parsing fails due to malformed JSON.
+     */
+    parse(jsonString, allowPartial = Allow.ALL, context) {
+        let stringToParse = jsonString;
+        const match = jsonString.match(thinkBlockRegex);
+        if (match) {
+            const thinkContent = match[1].trim();
+            const restOfString = match[2];
+            if (thinkContent) {
+                logger.debug('LLM <think> block detected and logged.', { ...context, thinkContent });
+            }
+            else {
+                logger.debug('Empty LLM <think> block detected.', context);
+            }
+            stringToParse = restOfString; // Parse only the part after </think>
+        }
+        // Trim leading/trailing whitespace which might interfere with JSON parsing, especially if only JSON is left
+        stringToParse = stringToParse.trim();
+        if (!stringToParse) {
+            // If after removing think block and trimming, the string is empty, it's an error
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, 'JSON string is empty after removing <think> block.', context);
+        }
+        try {
+            // Ensure the string starts with '{' or '[' if we expect an object or array after stripping <think>
+            // This helps catch cases where only non-JSON text remains.
+            if (!stringToParse.startsWith('{') && !stringToParse.startsWith('[')) {
+                // Check if it might be a simple string value that partial-json could parse
+                // Allow simple strings only if specifically permitted or Allow.ALL is used
+                const allowsString = (allowPartial & Allow.STR) === Allow.STR;
+                if (!allowsString && !stringToParse.startsWith('"')) { // Allow quoted strings if Allow.STR is set
+                    throw new Error('Remaining content does not appear to be valid JSON object or array.');
+                }
+                // If it starts with a quote and strings are allowed, let parsePartialJson handle it
+            }
+            return parsePartialJson(stringToParse, allowPartial);
+        }
+        catch (error) {
+            // Wrap the original error in an McpError for consistent error handling
+            // Include the original error message for better debugging context.
+            logger.error('Failed to parse JSON content.', { ...context, error: error.message, contentAttempted: stringToParse });
+            throw new McpError(BaseErrorCode.VALIDATION_ERROR, `Failed to parse JSON: ${error.message}`, {
+                ...context,
+                originalContent: stringToParse,
+                rawError: error instanceof Error ? error.stack : String(error) // Include raw error info
+            });
+        }
+    }
+}
+/**
+ * Singleton instance of the JsonParser utility.
+ */
+export const jsonParser = new JsonParser();