byterover-cli 0.2.1 → 0.3.0

package/dist/utils/error-handler.js

@@ -0,0 +1,169 @@
+/**
+ * Centralized error handling utility for CLI commands
+ *
+ * Provides user-friendly error messages based on error type:
+ * - Network errors: Check internet connection
+ * - Server errors: Retry later
+ * - Billing errors: Check account/payment
+ * - Auth errors: Re-login required
+ * - Validation errors: Check input
+ */
+import { isAxiosError } from 'axios';
+import { addErrorPrefix } from './emoji-helpers.js';
+export var ErrorType;
+(function (ErrorType) {
+    ErrorType["AUTH"] = "AUTH";
+    ErrorType["BILLING"] = "BILLING";
+    ErrorType["NETWORK"] = "NETWORK";
+    ErrorType["SERVER"] = "SERVER";
+    ErrorType["UNKNOWN"] = "UNKNOWN";
+    ErrorType["VALIDATION"] = "VALIDATION";
+})(ErrorType || (ErrorType = {}));
+/**
+ * Helper to create a ClassifiedError object
+ */
+function createClassifiedError(err, type, userMessage, customMessage) {
+    return {
+        message: customMessage || err.message,
+        originalError: err,
+        type,
+        userMessage,
+    };
+}
+/**
+ * Classify axios-specific errors
+ * Returns null if error is not an axios error
+ */
+function classifyAxiosError(error, err) {
+    if (!isAxiosError(error)) {
+        return null;
+    }
+    // Network connectivity issues
+    if (error.code === 'ENOTFOUND' || error.code === 'ECONNREFUSED' || error.code === 'ETIMEDOUT') {
+        return createClassifiedError(err, ErrorType.NETWORK, '❌ Network error: Unable to connect to ByteRover servers. Please check your internet connection and try again.');
+    }
+    // DNS resolution failed
+    if (error.code === 'EAI_AGAIN') {
+        return createClassifiedError(err, ErrorType.NETWORK, '❌ Network error: DNS resolution failed. Please check your internet connection and DNS settings.');
+    }
+    // Server returned error response
+    if (error.response) {
+        const { status } = error.response;
+        // Authentication errors (401, 403)
+        if (status === 401 || status === 403) {
+            return createClassifiedError(err, ErrorType.AUTH, '❌ Authentication failed: Your session has expired or is invalid. Please run "brv login" to re-authenticate.');
+        }
+        // Billing/quota errors (402, 429)
+        if (status === 402 || status === 429) {
+            return createClassifiedError(err, ErrorType.BILLING, '❌ Billing error: Your ByteRover account may not have sufficient credits or has reached quota limits. Please check your account settings.');
+        }
+        // Server errors (500, 502, 503, 504)
+        if (status >= 500) {
+            return createClassifiedError(err, ErrorType.SERVER, '❌ Server error: ByteRover servers are experiencing issues. Please try again in a few moments.');
+        }
+        // Client errors (400, 404, etc.)
+        if (status >= 400 && status < 500) {
+            // Try to extract error message from response
+            const responseData = error.response.data;
+            const errorMessage = typeof responseData === 'string' ? responseData : responseData?.message || responseData?.error || err.message;
+            return createClassifiedError(err, ErrorType.VALIDATION, `❌ Request error: ${errorMessage}`, errorMessage);
+        }
+    }
+    // Request was made but no response received
+    if (error.request) {
+        return createClassifiedError(err, ErrorType.NETWORK, '❌ Network error: No response from ByteRover servers. Please check your internet connection and try again.');
+    }
+    return null;
+}
+/**
+ * Classify error based on message keywords
+ * Returns null if no keywords match
+ */
+function classifyByMessageKeywords(err) {
+    const errorMessage = err.message.toLowerCase();
+    // Network-related keywords
+    if (errorMessage.includes('network') ||
+        errorMessage.includes('connection') ||
+        errorMessage.includes('timeout') ||
+        errorMessage.includes('enotfound') ||
+        errorMessage.includes('econnrefused')) {
+        return createClassifiedError(err, ErrorType.NETWORK, '❌ Network error: Unable to connect to ByteRover servers. Please check your internet connection and try again.');
+    }
+    // Authentication keywords
+    if (errorMessage.includes('authentication') ||
+        errorMessage.includes('unauthorized') ||
+        errorMessage.includes('forbidden') ||
+        errorMessage.includes('token') ||
+        errorMessage.includes('login')) {
+        return createClassifiedError(err, ErrorType.AUTH, '❌ Authentication failed: Your session has expired or is invalid. Please run "brv login" to re-authenticate.');
+    }
+    // Billing keywords
+    if (errorMessage.includes('billing') ||
+        errorMessage.includes('quota') ||
+        errorMessage.includes('limit') ||
+        errorMessage.includes('credits') ||
+        errorMessage.includes('payment')) {
+        return createClassifiedError(err, ErrorType.BILLING, '❌ Billing error: Your ByteRover account may not have sufficient credits or has reached quota limits. Please check your account settings.');
+    }
+    // Validation keywords
+    if (errorMessage.includes('invalid') ||
+        errorMessage.includes('required') ||
+        errorMessage.includes('missing') ||
+        errorMessage.includes('validation')) {
+        return createClassifiedError(err, ErrorType.VALIDATION, `❌ Validation error: ${err.message}`);
+    }
+    return null;
+}
+/**
+ * Classify error and return user-friendly message
+ */
+export function classifyError(error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    // Try axios error classification first
+    const axiosResult = classifyAxiosError(error, err);
+    if (axiosResult) {
+        return axiosResult;
+    }
+    // Try message-based classification
+    const messageResult = classifyByMessageKeywords(err);
+    if (messageResult) {
+        return messageResult;
+    }
+    // Default: unknown error
+    // Don't add prefix if error message already has emoji prefix
+    return createClassifiedError(err, ErrorType.UNKNOWN, addErrorPrefix(err.message));
+}
+/**
+ * Format error for display to user
+ *
+ * @param error - Error to format
+ * @returns User-friendly error message
+ */
+export function formatError(error) {
+    const classified = classifyError(error);
+    return classified.userMessage;
+}
+/**
+ * Check if error is a network error
+ */
+export function isNetworkError(error) {
+    return classifyError(error).type === ErrorType.NETWORK;
+}
+/**
+ * Check if error is a server error
+ */
+export function isServerError(error) {
+    return classifyError(error).type === ErrorType.SERVER;
+}
+/**
+ * Check if error is an authentication error
+ */
+export function isAuthError(error) {
+    return classifyError(error).type === ErrorType.AUTH;
+}
+/**
+ * Check if error is a billing error
+ */
+export function isBillingError(error) {
+    return classifyError(error).type === ErrorType.BILLING;
+}

package/dist/utils/error-helpers.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Safely extracts an error message from an unknown error value.
+ *
+ * This utility handles various error types that can be thrown in JavaScript:
+ * - Error instances (standard Error, custom Error subclasses)
+ * - Objects with message property
+ * - Strings
+ * - Other primitive types
+ *
+ * @param error - The caught error value (unknown type)
+ * @returns A string message describing the error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyOperation()
+ * } catch (error) {
+ *   throw new Error(`Operation failed: ${getErrorMessage(error)}`)
+ * }
+ * ```
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Type guard to check if a value is an Error instance.
+ * Useful for conditional error handling logic.
+ *
+ * @param error - The value to check
+ * @returns True if the value is an Error instance
+ */
+export declare function isError(error: unknown): error is Error;

package/dist/utils/error-helpers.js

@@ -0,0 +1,47 @@
+/**
+ * Safely extracts an error message from an unknown error value.
+ *
+ * This utility handles various error types that can be thrown in JavaScript:
+ * - Error instances (standard Error, custom Error subclasses)
+ * - Objects with message property
+ * - Strings
+ * - Other primitive types
+ *
+ * @param error - The caught error value (unknown type)
+ * @returns A string message describing the error
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyOperation()
+ * } catch (error) {
+ *   throw new Error(`Operation failed: ${getErrorMessage(error)}`)
+ * }
+ * ```
+ */
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (error && typeof error === 'object' && 'message' in error) {
+        const { message } = error;
+        if (typeof message === 'string') {
+            return message;
+        }
+    }
+    // Fallback for unknown error types
+    return String(error);
+}
+/**
+ * Type guard to check if a value is an Error instance.
+ * Useful for conditional error handling logic.
+ *
+ * @param error - The value to check
+ * @returns True if the value is an Error instance
+ */
+export function isError(error) {
+    return error instanceof Error;
+}

package/dist/utils/file-helpers.d.ts

@@ -13,3 +13,18 @@ export declare function findLatestFile(directory: string): Promise<string>;
  * @returns Number of files removed
  */
 export declare function clearDirectory(dirPath: string): Promise<number>;
+/**
+ * Sanitizes a folder path by replacing all special characters with a hyphen.
+ * @param folderName - The folder path need to sanitize
+ * @returns The sanitized folder path
+ */
+export declare function sanitizeFolderName(folderName: string): string;
+/**
+ * Lists all immediate children (files and directories) of the given directory,
+ * and, for each child folder, shows its own immediate children.
+ * @param dirPath The directory path whose children to list.
+ * @returns An object where keys are child names, and values are:
+ *   - for files: undefined
+ *   - for directories: an array of their immediate children
+ */
+export declare function listDirectoryChildren(dirPath?: string): Record<string, string[] | undefined>;

package/dist/utils/file-helpers.js

@@ -1,3 +1,4 @@
+import fs from 'node:fs';
 import { readdir, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 /**
@@ -43,3 +44,46 @@ export async function clearDirectory(dirPath) {
         throw error;
     }
 }
+/**
+ * Sanitizes a folder path by replacing all special characters with a hyphen.
+ * @param folderName - The folder path need to sanitize
+ * @returns The sanitized folder path
+ */
+export function sanitizeFolderName(folderName) {
+    return folderName.replaceAll(/[^\w\-./]/g, '-');
+}
+/**
+ * Lists all immediate children (files and directories) of the given directory,
+ * and, for each child folder, shows its own immediate children.
+ * @param dirPath The directory path whose children to list.
+ * @returns An object where keys are child names, and values are:
+ *   - for files: undefined
+ *   - for directories: an array of their immediate children
+ */
+export function listDirectoryChildren(dirPath = '.brv/context-tree') {
+    const result = {};
+    const children = fs.readdirSync(dirPath);
+    for (const child of children) {
+        const childPath = `${dirPath}/${child}`;
+        let stat;
+        try {
+            stat = fs.statSync(childPath);
+        }
+        catch {
+            result[child] = undefined;
+            continue;
+        }
+        if (stat.isDirectory()) {
+            try {
+                result[child] = fs.readdirSync(childPath);
+            }
+            catch {
+                result[child] = undefined;
+            }
+        }
+        else {
+            result[child] = undefined;
+        }
+    }
+    return result;
+}

package/dist/utils/oclif-error-helpers.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Helper utilities for handling oclif-specific errors
+ *
+ * These utilities help avoid duplicating error handling logic across commands
+ */
+/**
+ * Handle oclif error exit codes
+ *
+ * If the error has an oclif.exit property (set by this.error()), exit the process
+ * with that code. This prevents oclif from re-logging errors that were already displayed.
+ *
+ * @param error - Error with optional oclif metadata
+ * @returns true if error was handled (process exited), false if error should be re-thrown
+ *
+ * @example
+ * public async catch(error: Error & {oclif?: {exit: number}}): Promise<void> {
+ *   if (handleOclifExit(error)) return
+ *   // Handle other error cases...
+ * }
+ */
+export declare function handleOclifExit(error: Error & {
+    oclif?: {
+        exit: number;
+    };
+}): boolean;
+/**
+ * Check if error is an oclif validation error
+ *
+ * Validation errors include missing arguments, unexpected arguments, and missing flags.
+ * These should be re-thrown to let oclif's error handler display them properly.
+ *
+ * @param error - Error to check
+ * @returns true if error is a validation error
+ *
+ * @example
+ * if (isValidationError(error)) {
+ *   throw error // Let oclif handle it
+ * }
+ */
+export declare function isValidationError(error: Error): boolean;

package/dist/utils/oclif-error-helpers.js

@@ -0,0 +1,46 @@
+/**
+ * Helper utilities for handling oclif-specific errors
+ *
+ * These utilities help avoid duplicating error handling logic across commands
+ */
+/**
+ * Handle oclif error exit codes
+ *
+ * If the error has an oclif.exit property (set by this.error()), exit the process
+ * with that code. This prevents oclif from re-logging errors that were already displayed.
+ *
+ * @param error - Error with optional oclif metadata
+ * @returns true if error was handled (process exited), false if error should be re-thrown
+ *
+ * @example
+ * public async catch(error: Error & {oclif?: {exit: number}}): Promise<void> {
+ *   if (handleOclifExit(error)) return
+ *   // Handle other error cases...
+ * }
+ */
+export function handleOclifExit(error) {
+    if (error.oclif?.exit !== undefined) {
+        // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit
+        process.exit(error.oclif.exit);
+    }
+    return false;
+}
+/**
+ * Check if error is an oclif validation error
+ *
+ * Validation errors include missing arguments, unexpected arguments, and missing flags.
+ * These should be re-thrown to let oclif's error handler display them properly.
+ *
+ * @param error - Error to check
+ * @returns true if error is a validation error
+ *
+ * @example
+ * if (isValidationError(error)) {
+ *   throw error // Let oclif handle it
+ * }
+ */
+export function isValidationError(error) {
+    return (error.message.includes('Unexpected argument') ||
+        error.message.includes('Missing') ||
+        error.message.includes('required'));
+}

package/dist/utils/tool-display-formatter.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Tool Display Formatter
+ *
+ * Utilities for formatting tool call arguments and results in a concise,
+ * readable format for CLI display.
+ */
+/**
+ * Format a tool call with its arguments for display.
+ *
+ * Creates a concise, single-line representation of a tool call:
+ * - Truncates long strings with ellipsis
+ * - Shows relative paths or basenames for file paths
+ * - Omits undefined/null optional parameters
+ * - Formats arrays and objects as summaries
+ *
+ * @param toolName - Name of the tool being called
+ * @param args - Tool arguments object
+ * @returns Formatted string like "tool_name(arg1: value1, arg2: value2)"
+ *
+ * @example
+ * ```typescript
+ * formatToolCall('read_file', { filePath: '/long/path/to/file.ts', limit: 100 })
+ * // Returns: 'read_file(filePath: "file.ts", limit: 100)'
+ *
+ * formatToolCall('write_file', { filePath: 'test.ts', content: 'very long content...', createDirs: true })
+ * // Returns: 'write_file(filePath: "test.ts", content: "very long conte...", createDirs: true)'
+ * ```
+ */
+export declare function formatToolCall(toolName: string, args: Record<string, unknown>): string;
+/**
+ * Format a tool result for display.
+ *
+ * Creates a concise summary of the tool execution result:
+ * - For success: shows relevant metrics (file size, match count, etc.)
+ * - For errors: shows error message
+ * - Truncates long values
+ *
+ * @param toolName - Name of the tool that was executed
+ * @param success - Whether the tool execution succeeded
+ * @param result - Tool result (if successful)
+ * @param error - Error message (if failed)
+ * @returns Formatted result string
+ *
+ * @example
+ * ```typescript
+ * formatToolResult('write_file', true, { bytesWritten: 245 })
+ * // Returns: 'File written (245 bytes)'
+ *
+ * formatToolResult('read_file', false, undefined, 'ENOENT: no such file or directory')
+ * // Returns: 'ENOENT: no such file or directory'
+ * ```
+ */
+export declare function formatToolResult(toolName: string, success: boolean, result?: unknown, error?: string): string;