byterover-cli 0.4.1 → 1.0.0

package/dist/core/domain/cipher/errors/error-normalizer.js

@@ -0,0 +1,379 @@
+/**
+ * Error Normalizer
+ *
+ * Converts various error types into a unified, normalized format.
+ * Following the OpenCode pattern of MessageV2.fromError() for consistent
+ * error handling across providers.
+ *
+ * Key features:
+ * - Discriminated union for error types
+ * - Provider-agnostic error representation
+ * - Retryable error detection
+ * - Consistent error structure for UI consumption
+ */
+import { LlmConfigurationError, LlmError, LlmGenerationError, LlmMaxIterationsError, LlmMissingToolExecutorError, LlmRateLimitError, LlmResponseParsingError, LlmToolExecutionError, } from './llm-error.js';
+import { SessionCancelledError } from './session-error.js';
+import { ToolError } from './tool-error.js';
+/**
+ * Normalize abort-related errors.
+ */
+function normalizeAbortError(error) {
+    if (error instanceof DOMException && error.name === 'AbortError') {
+        return {
+            message: error.message || 'Operation was aborted',
+            type: 'aborted',
+        };
+    }
+    if (error instanceof Error && error.name === 'AbortError') {
+        return {
+            message: error.message || 'Operation was aborted',
+            type: 'aborted',
+        };
+    }
+    if (error instanceof SessionCancelledError) {
+        return {
+            message: error.message,
+            type: 'aborted',
+        };
+    }
+    return null;
+}
+/**
+ * Normalize LLM rate limit errors.
+ */
+function normalizeLlmRateLimitError(error, context) {
+    return {
+        message: error.message,
+        providerId: error.provider ?? context?.providerId ?? 'unknown',
+        retryAfter: error.retryAfter,
+        type: 'rate_limit',
+    };
+}
+/**
+ * Normalize LLM configuration errors.
+ */
+function normalizeLlmConfigError(error, context) {
+    return {
+        configKey: error.configKey,
+        message: error.message,
+        providerId: error.provider ?? context?.providerId,
+        type: 'config',
+    };
+}
+/**
+ * Normalize LLM tool execution errors.
+ */
+function normalizeLlmToolExecutionError(error) {
+    return {
+        message: error.message,
+        toolName: error.toolName,
+        type: 'tool',
+    };
+}
+/**
+ * Normalize LLM max iterations errors.
+ */
+function normalizeLlmMaxIterationsError(error) {
+    return {
+        maxTokens: error.maxIterations,
+        message: error.message,
+        type: 'output_length',
+    };
+}
+/**
+ * Normalize LLM response parsing errors.
+ */
+function normalizeLlmResponseParsingError(error, context) {
+    return {
+        isRetryable: false,
+        message: error.message,
+        model: error.model ?? context?.model,
+        providerId: error.provider ?? context?.providerId,
+        type: 'api',
+    };
+}
+/**
+ * Normalize LLM missing tool executor errors.
+ */
+function normalizeLlmMissingToolExecutorError(error, context) {
+    return {
+        configKey: 'toolExecutor',
+        message: error.message,
+        providerId: error.provider ?? context?.providerId,
+        type: 'config',
+    };
+}
+/**
+ * Normalize LLM generation errors.
+ */
+function normalizeLlmGenerationError(error, context) {
+    const isRetryable = isRetryableError(error);
+    return {
+        isRetryable,
+        message: error.message,
+        model: error.model ?? context?.model,
+        providerId: error.provider ?? context?.providerId,
+        type: 'api',
+    };
+}
+/**
+ * Normalize generic LLM errors.
+ */
+function normalizeGenericLlmError(error, context) {
+    const isRetryable = isRetryableError(error);
+    return {
+        isRetryable,
+        message: error.message,
+        model: error.model ?? context?.model,
+        providerId: error.provider ?? context?.providerId,
+        type: 'api',
+    };
+}
+/**
+ * Normalize LLM-specific errors.
+ */
+function normalizeLlmError(error, context) {
+    if (error instanceof LlmRateLimitError) {
+        return normalizeLlmRateLimitError(error, context);
+    }
+    if (error instanceof LlmConfigurationError) {
+        return normalizeLlmConfigError(error, context);
+    }
+    if (error instanceof LlmToolExecutionError) {
+        return normalizeLlmToolExecutionError(error);
+    }
+    if (error instanceof LlmMaxIterationsError) {
+        return normalizeLlmMaxIterationsError(error);
+    }
+    if (error instanceof LlmResponseParsingError) {
+        return normalizeLlmResponseParsingError(error, context);
+    }
+    if (error instanceof LlmMissingToolExecutorError) {
+        return normalizeLlmMissingToolExecutorError(error, context);
+    }
+    if (error instanceof LlmGenerationError) {
+        return normalizeLlmGenerationError(error, context);
+    }
+    if (error instanceof LlmError) {
+        return normalizeGenericLlmError(error, context);
+    }
+    return null;
+}
+/**
+ * Normalize tool-related errors.
+ */
+function normalizeToolError(error) {
+    if (error instanceof ToolError) {
+        const toolName = error.details?.toolName ?? 'unknown';
+        return {
+            message: error.message,
+            toolName,
+            type: 'tool',
+        };
+    }
+    return null;
+}
+/**
+ * Normalize generic Error instances.
+ */
+function normalizeGenericError(error, context) {
+    if (isAuthError(error)) {
+        return {
+            message: error.message,
+            providerId: context?.providerId ?? 'unknown',
+            type: 'auth',
+        };
+    }
+    if (isRateLimitPattern(error.message)) {
+        return {
+            message: error.message,
+            providerId: context?.providerId ?? 'unknown',
+            type: 'rate_limit',
+        };
+    }
+    return {
+        message: error.message,
+        originalError: error,
+        type: 'unknown',
+    };
+}
+/**
+ * Normalize any error into a consistent format.
+ *
+ * This function handles all known error types and converts them
+ * to a unified NormalizedError format for consistent handling.
+ *
+ * @param error - The error to normalize
+ * @param context - Optional context about the operation
+ * @returns Normalized error with consistent structure
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await llm.generate(prompt)
+ * } catch (error) {
+ *   const normalized = normalizeError(error, { providerId: 'claude' })
+ *
+ *   switch (normalized.type) {
+ *     case 'rate_limit':
+ *       await sleep(normalized.retryAfter * 1000)
+ *       break
+ *     case 'auth':
+ *       showLoginPrompt()
+ *       break
+ *     default:
+ *       logError(normalized.message)
+ *   }
+ * }
+ * ```
+ */
+export function normalizeError(error, context) {
+    if (error === null || error === undefined) {
+        return {
+            message: 'Unknown error occurred',
+            type: 'unknown',
+        };
+    }
+    const abortError = normalizeAbortError(error);
+    if (abortError) {
+        return abortError;
+    }
+    const llmError = normalizeLlmError(error, context);
+    if (llmError) {
+        return llmError;
+    }
+    const toolError = normalizeToolError(error);
+    if (toolError) {
+        return toolError;
+    }
+    if (error instanceof Error) {
+        return normalizeGenericError(error, context);
+    }
+    if (typeof error === 'string') {
+        return {
+            message: error,
+            type: 'unknown',
+        };
+    }
+    if (typeof error === 'object' && 'message' in error && typeof error.message === 'string') {
+        return {
+            message: error.message,
+            type: 'unknown',
+        };
+    }
+    return {
+        message: String(error),
+        type: 'unknown',
+    };
+}
+/**
+ * Check if an error is retryable.
+ */
+function isRetryableError(error) {
+    const message = error.message.toLowerCase();
+    // Network errors are usually retryable
+    if (message.includes('network') || message.includes('timeout') || message.includes('econnreset')) {
+        return true;
+    }
+    // Server errors (5xx) are usually retryable
+    if (message.includes('500') || message.includes('502') || message.includes('503') || message.includes('504')) {
+        return true;
+    }
+    // Rate limits are retryable
+    if (message.includes('rate limit') || message.includes('too many requests') || message.includes('429')) {
+        return true;
+    }
+    // Overloaded errors are retryable
+    if (message.includes('overloaded') || message.includes('capacity')) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if an error looks like an auth error.
+ */
+function isAuthError(error) {
+    const message = error.message.toLowerCase();
+    return (message.includes('unauthorized') ||
+        message.includes('authentication') ||
+        message.includes('api key') ||
+        message.includes('invalid key') ||
+        message.includes('401') ||
+        message.includes('403'));
+}
+/**
+ * Check if a message looks like a rate limit error.
+ */
+function isRateLimitPattern(message) {
+    const lower = message.toLowerCase();
+    return (lower.includes('rate limit') ||
+        lower.includes('too many requests') ||
+        lower.includes('429') ||
+        lower.includes('quota exceeded'));
+}
+/**
+ * Check if a normalized error is retryable.
+ */
+export function isNormalizedErrorRetryable(error) {
+    switch (error.type) {
+        case 'aborted': {
+            return false;
+        }
+        case 'api': {
+            return error.isRetryable;
+        }
+        case 'auth': {
+            return false;
+        }
+        case 'config': {
+            return false;
+        }
+        case 'output_length': {
+            return false;
+        }
+        case 'rate_limit': {
+            return true;
+        }
+        case 'tool': {
+            return false;
+        }
+        case 'unknown': {
+            return false;
+        }
+    }
+}
+/**
+ * Get a user-friendly message for a normalized error.
+ */
+export function getErrorDisplayMessage(error) {
+    switch (error.type) {
+        case 'aborted': {
+            return 'Operation was cancelled.';
+        }
+        case 'api': {
+            return error.isRetryable
+                ? 'Temporary error. Please try again.'
+                : `API error: ${error.message}`;
+        }
+        case 'auth': {
+            return `Authentication failed with ${error.providerId}. Please check your API key.`;
+        }
+        case 'config': {
+            return `Configuration error: ${error.message}`;
+        }
+        case 'output_length': {
+            return 'Response was too long and was truncated.';
+        }
+        case 'rate_limit': {
+            return error.retryAfter
+                ? `Rate limit exceeded. Retry in ${error.retryAfter} seconds.`
+                : 'Rate limit exceeded. Please wait and try again.';
+        }
+        case 'tool': {
+            return `Tool "${error.toolName}" failed: ${error.message}`;
+        }
+        case 'unknown': {
+            return error.message || 'An unexpected error occurred.';
+        }
+    }
+}

package/dist/core/domain/cipher/errors/file-system-error.d.ts

@@ -20,8 +20,9 @@ export declare class FileNotFoundError extends FileSystemError {
     /**
      * Creates a new file not found error
      * @param path - Path to the file that was not found
+     * @param customMessage - Optional custom message (e.g., with suggestions)
      */
-    constructor(path: string);
+    constructor(path: string, customMessage?: string);
 }
 /**
  * Error thrown when a directory is not found.

package/dist/core/domain/cipher/errors/file-system-error.js

@@ -25,9 +25,10 @@ export class FileNotFoundError extends FileSystemError {
     /**
      * Creates a new file not found error
      * @param path - Path to the file that was not found
+     * @param customMessage - Optional custom message (e.g., with suggestions)
      */
-    constructor(path) {
-        super(`File not found: ${path}`, 'FILE_NOT_FOUND', { path });
+    constructor(path, customMessage) {
+        super(customMessage ?? `File not found: ${path}`, 'FILE_NOT_FOUND', { path });
         this.name = 'FileNotFoundError';
     }
 }

package/dist/core/domain/cipher/errors/system-prompt-error-codes.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Error codes for system prompt operations.
+ *
+ * Used by SystemPromptError factory to create structured error objects.
+ */
+export declare enum SystemPromptErrorCode {
+    /**
+     * Cache operation failed.
+     *
+     * Error during cache read, write, or invalidation.
+     */
+    CACHE_OPERATION_FAILED = "CACHE_OPERATION_FAILED",
+    /**
+     * Prompt configuration is invalid.
+     *
+     * YAML structure doesn't match expected schema.
+     */
+    CONFIG_INVALID = "CONFIG_INVALID",
+    /**
+     * Required field missing from configuration.
+     *
+     * A mandatory field like 'prompt' or 'prompts' is not present.
+     */
+    CONFIG_MISSING_FIELD = "CONFIG_MISSING_FIELD",
+    /**
+     * Contributor execution failed.
+     *
+     * Error occurred while generating contributor content.
+     */
+    CONTRIBUTOR_EXECUTION_FAILED = "CONTRIBUTOR_EXECUTION_FAILED",
+    /**
+     * Invalid contributor configuration.
+     *
+     * Contributor config doesn't match expected structure.
+     */
+    CONTRIBUTOR_INVALID_CONFIG = "CONTRIBUTOR_INVALID_CONFIG",
+    /**
+     * Contributor not found in registry.
+     *
+     * The specified contributor ID is not registered.
+     */
+    CONTRIBUTOR_NOT_FOUND = "CONTRIBUTOR_NOT_FOUND",
+    /**
+     * Invalid file type for prompt loading.
+     *
+     * File extension is not in the allowed list (e.g., .yml, .yaml).
+     */
+    FILE_INVALID_TYPE = "FILE_INVALID_TYPE",
+    /**
+     * Prompt file not found.
+     *
+     * The specified YAML prompt file does not exist at the expected path.
+     */
+    FILE_NOT_FOUND = "FILE_NOT_FOUND",
+    /**
+     * Failed to read prompt file.
+     *
+     * I/O error when attempting to read file contents.
+     */
+    FILE_READ_FAILED = "FILE_READ_FAILED",
+    /**
+     * File exceeds maximum allowed size.
+     *
+     * Prompt files have a size limit to prevent memory issues.
+     */
+    FILE_TOO_LARGE = "FILE_TOO_LARGE",
+    /**
+     * Template rendering failed.
+     *
+     * Error during variable substitution in template.
+     */
+    TEMPLATE_RENDER_FAILED = "TEMPLATE_RENDER_FAILED",
+    /**
+     * Required template variable is missing.
+     *
+     * A placeholder in the template has no corresponding value.
+     */
+    TEMPLATE_VARIABLE_MISSING = "TEMPLATE_VARIABLE_MISSING"
+}

package/dist/core/domain/cipher/errors/system-prompt-error-codes.js

@@ -0,0 +1,80 @@
+/**
+ * Error codes for system prompt operations.
+ *
+ * Used by SystemPromptError factory to create structured error objects.
+ */
+export var SystemPromptErrorCode;
+(function (SystemPromptErrorCode) {
+    /**
+     * Cache operation failed.
+     *
+     * Error during cache read, write, or invalidation.
+     */
+    SystemPromptErrorCode["CACHE_OPERATION_FAILED"] = "CACHE_OPERATION_FAILED";
+    /**
+     * Prompt configuration is invalid.
+     *
+     * YAML structure doesn't match expected schema.
+     */
+    SystemPromptErrorCode["CONFIG_INVALID"] = "CONFIG_INVALID";
+    /**
+     * Required field missing from configuration.
+     *
+     * A mandatory field like 'prompt' or 'prompts' is not present.
+     */
+    SystemPromptErrorCode["CONFIG_MISSING_FIELD"] = "CONFIG_MISSING_FIELD";
+    /**
+     * Contributor execution failed.
+     *
+     * Error occurred while generating contributor content.
+     */
+    SystemPromptErrorCode["CONTRIBUTOR_EXECUTION_FAILED"] = "CONTRIBUTOR_EXECUTION_FAILED";
+    /**
+     * Invalid contributor configuration.
+     *
+     * Contributor config doesn't match expected structure.
+     */
+    SystemPromptErrorCode["CONTRIBUTOR_INVALID_CONFIG"] = "CONTRIBUTOR_INVALID_CONFIG";
+    /**
+     * Contributor not found in registry.
+     *
+     * The specified contributor ID is not registered.
+     */
+    SystemPromptErrorCode["CONTRIBUTOR_NOT_FOUND"] = "CONTRIBUTOR_NOT_FOUND";
+    /**
+     * Invalid file type for prompt loading.
+     *
+     * File extension is not in the allowed list (e.g., .yml, .yaml).
+     */
+    SystemPromptErrorCode["FILE_INVALID_TYPE"] = "FILE_INVALID_TYPE";
+    /**
+     * Prompt file not found.
+     *
+     * The specified YAML prompt file does not exist at the expected path.
+     */
+    SystemPromptErrorCode["FILE_NOT_FOUND"] = "FILE_NOT_FOUND";
+    /**
+     * Failed to read prompt file.
+     *
+     * I/O error when attempting to read file contents.
+     */
+    SystemPromptErrorCode["FILE_READ_FAILED"] = "FILE_READ_FAILED";
+    /**
+     * File exceeds maximum allowed size.
+     *
+     * Prompt files have a size limit to prevent memory issues.
+     */
+    SystemPromptErrorCode["FILE_TOO_LARGE"] = "FILE_TOO_LARGE";
+    /**
+     * Template rendering failed.
+     *
+     * Error during variable substitution in template.
+     */
+    SystemPromptErrorCode["TEMPLATE_RENDER_FAILED"] = "TEMPLATE_RENDER_FAILED";
+    /**
+     * Required template variable is missing.
+     *
+     * A placeholder in the template has no corresponding value.
+     */
+    SystemPromptErrorCode["TEMPLATE_VARIABLE_MISSING"] = "TEMPLATE_VARIABLE_MISSING";
+})(SystemPromptErrorCode || (SystemPromptErrorCode = {}));

package/dist/core/domain/cipher/errors/system-prompt-error.d.ts

@@ -0,0 +1,114 @@
+import { SystemPromptErrorCode } from './system-prompt-error-codes.js';
+/**
+ * Base error class for system prompt operations.
+ *
+ * All system prompt-specific errors use this class with factory methods.
+ */
+export declare class SystemPromptError extends Error {
+    readonly code: SystemPromptErrorCode;
+    readonly details?: Record<string, unknown>;
+    readonly suggestion?: string;
+    /**
+     * Creates a new system prompt error.
+     *
+     * @param message - Error message describing what went wrong
+     * @param code - Error code for categorization
+     * @param details - Additional error context
+     * @param suggestion - Optional recovery suggestion
+     */
+    constructor(message: string, code: SystemPromptErrorCode, details?: Record<string, unknown>, suggestion?: string);
+    /**
+     * Factory method: Cache operation failed.
+     *
+     * @param operation - The cache operation that failed (get, set, invalidate)
+     * @param reason - Reason for the failure
+     * @returns SystemPromptError instance
+     */
+    static cacheOperationFailed(operation: string, reason: string): SystemPromptError;
+    /**
+     * Factory method: Prompt configuration is invalid.
+     *
+     * @param reason - Reason why configuration is invalid
+     * @param validationErrors - Optional validation error details
+     * @returns SystemPromptError instance
+     */
+    static configInvalid(reason: string, validationErrors?: unknown): SystemPromptError;
+    /**
+     * Factory method: Required field missing from configuration.
+     *
+     * @param field - Name of the missing field
+     * @param filepath - Path to the config file
+     * @returns SystemPromptError instance
+     */
+    static configMissingField(field: string, filepath: string): SystemPromptError;
+    /**
+     * Factory method: Contributor execution failed.
+     *
+     * @param contributorId - ID of the failing contributor
+     * @param reason - Reason for the failure
+     * @returns SystemPromptError instance
+     */
+    static contributorExecutionFailed(contributorId: string, reason: string): SystemPromptError;
+    /**
+     * Factory method: Invalid contributor configuration.
+     *
+     * @param config - The invalid configuration object
+     * @returns SystemPromptError instance
+     */
+    static contributorInvalidConfig(config: unknown): SystemPromptError;
+    /**
+     * Factory method: Contributor not found in registry.
+     *
+     * @param contributorId - ID of the missing contributor
+     * @returns SystemPromptError instance
+     */
+    static contributorNotFound(contributorId: string): SystemPromptError;
+    /**
+     * Factory method: Prompt file not found.
+     *
+     * @param filepath - Path to the missing file
+     * @returns SystemPromptError instance
+     */
+    static fileNotFound(filepath: string): SystemPromptError;
+    /**
+     * Factory method: Failed to read prompt file.
+     *
+     * @param filepath - Path to the file
+     * @param reason - Reason for the failure
+     * @returns SystemPromptError instance
+     */
+    static fileReadFailed(filepath: string, reason: string): SystemPromptError;
+    /**
+     * Factory method: File exceeds maximum allowed size.
+     *
+     * @param filepath - Path to the file
+     * @param size - Actual file size in bytes
+     * @param maxSize - Maximum allowed size in bytes
+     * @returns SystemPromptError instance
+     */
+    static fileTooLarge(filepath: string, size: number, maxSize: number): SystemPromptError;
+    /**
+     * Factory method: Invalid file type for prompt loading.
+     *
+     * @param filepath - Path to the invalid file
+     * @param allowedExtensions - List of allowed file extensions
+     * @returns SystemPromptError instance
+     */
+    static invalidFileType(filepath: string, allowedExtensions: string[]): SystemPromptError;
+    /**
+     * Factory method: Template rendering failed.
+     *
+     * @param reason - Reason for the failure
+     * @param templatePreview - Preview of the template (first 100 chars)
+     * @returns SystemPromptError instance
+     */
+    static templateRenderFailed(reason: string, templatePreview?: string): SystemPromptError;
+    /**
+     * Factory method: Required template variable is missing.
+     *
+     * @param variable - Name of the missing variable
+     * @param template - Path or identifier of the template
+     * @returns SystemPromptError instance
+     */
+    static templateVariableMissing(variable: string, template: string): SystemPromptError;
+}