@magentrix-corp/magentrix-cli 1.3.16 → 1.3.17

package/utils/iris/errors.js

@@ -1,537 +1,537 @@
-/**
- * Error handling utilities for Iris Vue integration.
- * Provides user-friendly error messages with actionable solutions.
- */
-
-import chalk from 'chalk';
-
-/**
- * Error types for categorization and handling.
- */
-export const ErrorTypes = {
-    PERMISSION: 'PERMISSION',
-    DISK_FULL: 'DISK_FULL',
-    FILE_LOCKED: 'FILE_LOCKED',
-    NOT_FOUND: 'NOT_FOUND',
-    INVALID_CONFIG: 'INVALID_CONFIG',
-    NETWORK: 'NETWORK',
-    VALIDATION: 'VALIDATION',
-    CONCURRENT_OPERATION: 'CONCURRENT_OPERATION',
-    TIMEOUT: 'TIMEOUT',
-    CORRUPTED: 'CORRUPTED',
-    UNKNOWN: 'UNKNOWN'
-};
-
-/**
- * Detect the type of error from an Error object or error code.
- *
- * @param {Error | string} error - The error to analyze
- * @returns {string} - One of ErrorTypes
- */
-export function detectErrorType(error) {
-    const code = error?.code || error;
-    const message = (error?.message || String(error)).toLowerCase();
-
-    // Permission errors
-    if (code === 'EACCES' || code === 'EPERM' || message.includes('permission denied')) {
-        return ErrorTypes.PERMISSION;
-    }
-
-    // Disk full errors
-    if (code === 'ENOSPC' || message.includes('no space left') || message.includes('disk full')) {
-        return ErrorTypes.DISK_FULL;
-    }
-
-    // File locked errors (Windows mainly)
-    if (code === 'EBUSY' || code === 'ENOTEMPTY' || message.includes('resource busy') ||
-        message.includes('being used by another process')) {
-        return ErrorTypes.FILE_LOCKED;
-    }
-
-    // Not found errors
-    if (code === 'ENOENT' || message.includes('no such file') || message.includes('not found')) {
-        return ErrorTypes.NOT_FOUND;
-    }
-
-    // Network errors
-    if (code === 'ENOTFOUND' || code === 'ECONNREFUSED' || code === 'ECONNRESET' ||
-        code === 'ETIMEDOUT' || message.includes('network') || message.includes('fetch')) {
-        return ErrorTypes.NETWORK;
-    }
-
-    // JSON/config parsing errors
-    if (message.includes('json') || message.includes('parse') || message.includes('syntax')) {
-        return ErrorTypes.CORRUPTED;
-    }
-
-    // Timeout errors
-    if (code === 'ETIMEDOUT' || message.includes('timeout')) {
-        return ErrorTypes.TIMEOUT;
-    }
-
-    return ErrorTypes.UNKNOWN;
-}
-
-/**
- * Format a permission error with helpful guidance.
- *
- * @param {Object} options - Error context
- * @param {string} options.operation - What operation failed (e.g., 'write', 'delete', 'read')
- * @param {string} options.path - The path that caused the error
- * @param {string} options.platform - The platform ('win32', 'darwin', 'linux')
- * @returns {string} - Formatted error message
- */
-export function formatPermissionError(options) {
-    const { operation = 'access', path = '', platform = process.platform } = options;
-
-    const lines = [
-        '',
-        chalk.bgRed.white.bold(' Permission Error '),
-        chalk.red('─'.repeat(50)),
-        '',
-        chalk.white(`Unable to ${operation} files at:`),
-        chalk.gray(`  ${path}`),
-        '',
-        chalk.cyan('Possible causes:'),
-    ];
-
-    if (platform === 'win32') {
-        lines.push(
-            chalk.gray('  1. File is open in another program (VS Code, Explorer, antivirus)'),
-            chalk.gray('  2. You need to run the command as Administrator'),
-            chalk.gray('  3. The file is marked as read-only'),
-            '',
-            chalk.cyan('Solutions:'),
-            chalk.white('  1. Close any programs that might have the file open'),
-            chalk.white('  2. Run your terminal as Administrator:'),
-            chalk.gray('     Right-click terminal > "Run as administrator"'),
-            chalk.white('  3. Check file properties and uncheck "Read-only"'),
-            chalk.white('  4. Temporarily disable antivirus real-time scanning')
-        );
-    } else {
-        lines.push(
-            chalk.gray('  1. Files are owned by a different user'),
-            chalk.gray('  2. Insufficient permissions on directory'),
-            chalk.gray('  3. File system is mounted read-only'),
-            '',
-            chalk.cyan('Solutions:'),
-            chalk.white('  1. Change ownership of the files:'),
-            chalk.yellow(`     sudo chown -R $(whoami) "${path}"`),
-            chalk.white('  2. Fix directory permissions:'),
-            chalk.yellow(`     chmod -R u+rwX "${path}"`),
-            chalk.white('  3. Use sudo for this operation (if appropriate):'),
-            chalk.yellow('     sudo magentrix <command>')
-        );
-    }
-
-    lines.push('', chalk.red('─'.repeat(50)), '');
-
-    return lines.join('\n');
-}
-
-/**
- * Format a disk full error with helpful guidance.
- *
- * @param {Object} options - Error context
- * @param {string} options.operation - What operation failed
- * @param {string} options.path - The path that caused the error
- * @returns {string} - Formatted error message
- */
-export function formatDiskFullError(options) {
-    const { operation = 'write', path = '' } = options;
-    const platform = process.platform;
-
-    const lines = [
-        '',
-        chalk.bgRed.white.bold(' Disk Full '),
-        chalk.red('─'.repeat(50)),
-        '',
-        chalk.white(`Cannot ${operation} - no disk space available.`),
-        chalk.gray(`  Path: ${path}`),
-        '',
-        chalk.cyan('Solutions:'),
-    ];
-
-    if (platform === 'win32') {
-        lines.push(
-            chalk.white('  1. Free up disk space:'),
-            chalk.gray('     - Empty the Recycle Bin'),
-            chalk.gray('     - Run Disk Cleanup (cleanmgr.exe)'),
-            chalk.gray('     - Uninstall unused programs'),
-            chalk.white('  2. Clear npm cache:'),
-            chalk.yellow('     npm cache clean --force'),
-            chalk.white('  3. Check available space:'),
-            chalk.yellow('     wmic logicaldisk get size,freespace,caption')
-        );
-    } else {
-        lines.push(
-            chalk.white('  1. Check disk usage:'),
-            chalk.yellow('     df -h'),
-            chalk.white('  2. Find large files:'),
-            chalk.yellow('     du -sh * | sort -rh | head -20'),
-            chalk.white('  3. Clear npm cache:'),
-            chalk.yellow('     npm cache clean --force'),
-            chalk.white('  4. Clear system logs (macOS):'),
-            chalk.yellow('     sudo rm -rf /private/var/log/*'),
-            chalk.white('  5. Clear trash:'),
-            chalk.yellow('     rm -rf ~/.Trash/*')
-        );
-    }
-
-    lines.push('', chalk.red('─'.repeat(50)), '');
-
-    return lines.join('\n');
-}
-
-/**
- * Format a file locked error with helpful guidance.
- *
- * @param {Object} options - Error context
- * @param {string} options.path - The path that caused the error
- * @returns {string} - Formatted error message
- */
-export function formatFileLockError(options) {
-    const { path = '' } = options;
-    const platform = process.platform;
-
-    const lines = [
-        '',
-        chalk.bgYellow.black.bold(' File In Use '),
-        chalk.yellow('─'.repeat(50)),
-        '',
-        chalk.white('Cannot modify file - it is being used by another program.'),
-        chalk.gray(`  Path: ${path}`),
-        '',
-        chalk.cyan('This commonly happens when:'),
-        chalk.gray('  - Your IDE (VS Code, WebStorm) has the file open'),
-        chalk.gray('  - A dev server is running and watching files'),
-        chalk.gray('  - Antivirus is scanning the file'),
-        chalk.gray('  - Another terminal has the directory open'),
-        '',
-        chalk.cyan('Solutions:'),
-    ];
-
-    if (platform === 'win32') {
-        lines.push(
-            chalk.white('  1. Close applications that might be using the file'),
-            chalk.white('  2. Close any Vue/React dev servers running from this project'),
-            chalk.white('  3. Close and reopen VS Code'),
-            chalk.white('  4. Find what is using the file:'),
-            chalk.gray('     - Open Resource Monitor (resmon.exe)'),
-            chalk.gray('     - Go to CPU > Associated Handles'),
-            chalk.gray('     - Search for the filename')
-        );
-    } else {
-        lines.push(
-            chalk.white('  1. Close applications that might be using the file'),
-            chalk.white('  2. Stop any running dev servers'),
-            chalk.white('  3. Find what is using the file:'),
-            chalk.yellow(`     lsof "${path}"`),
-            chalk.white('  4. Wait a few seconds and try again')
-        );
-    }
-
-    lines.push('', chalk.yellow('─'.repeat(50)), '');
-
-    return lines.join('\n');
-}
-
-/**
- * Format a network error with helpful guidance.
- *
- * @param {Object} options - Error context
- * @param {string} options.url - The URL that failed
- * @param {Error} options.error - The original error
- * @returns {string} - Formatted error message
- */
-export function formatNetworkError(options) {
-    const { url = '', error } = options;
-    const code = error?.code || '';
-    const message = error?.message || '';
-
-    const lines = [
-        '',
-        chalk.bgRed.white.bold(' Network Error '),
-        chalk.red('─'.repeat(50)),
-        '',
-        chalk.white('Failed to connect to the server.'),
-        chalk.gray(`  URL: ${url}`),
-        chalk.gray(`  Error: ${message}`),
-        '',
-        chalk.cyan('Possible causes:'),
-    ];
-
-    if (code === 'ENOTFOUND' || message.includes('getaddrinfo')) {
-        lines.push(
-            chalk.gray('  - The server hostname could not be resolved'),
-            chalk.gray('  - DNS server issues'),
-            chalk.gray('  - Typo in the URL'),
-            '',
-            chalk.cyan('Solutions:'),
-            chalk.white('  1. Check that the URL is correct'),
-            chalk.white('  2. Verify your internet connection'),
-            chalk.white('  3. Try accessing the URL in a browser')
-        );
-    } else if (code === 'ECONNREFUSED') {
-        lines.push(
-            chalk.gray('  - The server is not running'),
-            chalk.gray('  - Wrong port number'),
-            chalk.gray('  - Firewall blocking the connection'),
-            '',
-            chalk.cyan('Solutions:'),
-            chalk.white('  1. Verify the server is running'),
-            chalk.white('  2. Check if the URL and port are correct'),
-            chalk.white('  3. Check firewall settings')
-        );
-    } else if (code === 'ETIMEDOUT' || message.includes('timeout')) {
-        lines.push(
-            chalk.gray('  - Server took too long to respond'),
-            chalk.gray('  - Network congestion'),
-            chalk.gray('  - Server might be overloaded'),
-            '',
-            chalk.cyan('Solutions:'),
-            chalk.white('  1. Wait a moment and try again'),
-            chalk.white('  2. Check if you can access the server in a browser'),
-            chalk.white('  3. Try from a different network')
-        );
-    } else {
-        lines.push(
-            chalk.gray('  - Network connectivity issues'),
-            chalk.gray('  - Server is unreachable'),
-            '',
-            chalk.cyan('Solutions:'),
-            chalk.white('  1. Check your internet connection'),
-            chalk.white('  2. Try again in a few minutes'),
-            chalk.white('  3. Verify the URL is correct')
-        );
-    }
-
-    lines.push('', chalk.red('─'.repeat(50)), '');
-
-    return lines.join('\n');
-}
-
-/**
- * Format a corrupted config error with helpful guidance.
- *
- * @param {Object} options - Error context
- * @param {string} options.configPath - Path to the corrupted config
- * @param {Error} options.error - The original error
- * @returns {string} - Formatted error message
- */
-export function formatCorruptedConfigError(options) {
-    const { configPath = '', error } = options;
-    const message = error?.message || 'Invalid JSON format';
-
-    const lines = [
-        '',
-        chalk.bgRed.white.bold(' Config File Corrupted '),
-        chalk.red('─'.repeat(50)),
-        '',
-        chalk.white('The configuration file could not be read due to invalid format.'),
-        chalk.gray(`  Path: ${configPath}`),
-        chalk.gray(`  Error: ${message}`),
-        '',
-        chalk.cyan('This can happen when:'),
-        chalk.gray('  - A previous write was interrupted'),
-        chalk.gray('  - The file was manually edited with invalid JSON'),
-        chalk.gray('  - Disk errors corrupted the file'),
-        '',
-        chalk.cyan('Solutions:'),
-        chalk.white('  1. Check if a backup exists:'),
-        chalk.yellow(`     ls -la "${configPath}.bak"`),
-        chalk.white('  2. If backup exists, restore it:'),
-        chalk.yellow(`     cp "${configPath}.bak" "${configPath}"`),
-        chalk.white('  3. If no backup, you may need to delete and recreate:'),
-        chalk.yellow(`     rm "${configPath}"`),
-        chalk.gray('     Then re-run your command to regenerate the config.'),
-        '',
-        chalk.bgYellow.black(' Warning '),
-        chalk.yellow('  Deleting the config will lose your linked project history.'),
-        chalk.yellow('  You will need to re-link your Vue projects.'),
-        '',
-        chalk.red('─'.repeat(50)),
-        ''
-    ];
-
-    return lines.join('\n');
-}
-
-/**
- * Format a concurrent operation error with helpful guidance.
- *
- * @param {Object} options - Error context
- * @param {string} options.operation - The operation that was blocked
- * @param {string} options.lockHolder - Description of what holds the lock
- * @param {string} options.lockFile - Path to the lock file
- * @returns {string} - Formatted error message
- */
-export function formatConcurrentOperationError(options) {
-    const { operation = 'this operation', lockHolder = 'another process', lockFile = '' } = options;
-
-    const lines = [
-        '',
-        chalk.bgYellow.black.bold(' Operation Blocked '),
-        chalk.yellow('─'.repeat(50)),
-        '',
-        chalk.white(`Cannot ${operation} - ${lockHolder} is currently running.`),
-        '',
-        chalk.cyan('Why this happens:'),
-        chalk.gray('  Running multiple operations simultaneously can cause:'),
-        chalk.gray('  - File corruption'),
-        chalk.gray('  - Data loss'),
-        chalk.gray('  - Inconsistent state'),
-        '',
-        chalk.cyan('Solutions:'),
-        chalk.white('  1. Wait for the other operation to complete'),
-        chalk.white('  2. If the other operation crashed, remove the lock file:'),
-        lockFile ? chalk.yellow(`     rm "${lockFile}"`) : chalk.gray('     (lock file path not available)'),
-        chalk.white('  3. Check for running magentrix processes:'),
-        chalk.yellow('     ps aux | grep magentrix'),
-        '',
-        chalk.yellow('─'.repeat(50)),
-        ''
-    ];
-
-    return lines.join('\n');
-}
-
-/**
- * Format a timeout error with helpful guidance.
- *
- * @param {Object} options - Error context
- * @param {string} options.operation - What operation timed out
- * @param {number} options.timeoutMs - The timeout value in milliseconds
- * @returns {string} - Formatted error message
- */
-export function formatTimeoutError(options) {
-    const { operation = 'Operation', timeoutMs = 0 } = options;
-    const seconds = Math.round(timeoutMs / 1000);
-
-    const lines = [
-        '',
-        chalk.bgYellow.black.bold(' Operation Timed Out '),
-        chalk.yellow('─'.repeat(50)),
-        '',
-        chalk.white(`${operation} did not complete within ${seconds} seconds.`),
-        '',
-        chalk.cyan('Possible causes:'),
-        chalk.gray('  - The server is slow or unresponsive'),
-        chalk.gray('  - Network latency is high'),
-        chalk.gray('  - Large amount of data being processed'),
-        '',
-        chalk.cyan('Solutions:'),
-        chalk.white('  1. Try running the command again'),
-        chalk.white('  2. Check your network connection'),
-        chalk.white('  3. If working with large files, allow more time'),
-        '',
-        chalk.yellow('─'.repeat(50)),
-        ''
-    ];
-
-    return lines.join('\n');
-}
-
-/**
- * Format any error with automatic type detection.
- *
- * @param {Error} error - The error to format
- * @param {Object} context - Additional context for the error
- * @returns {string} - Formatted error message
- */
-export function formatError(error, context = {}) {
-    const errorType = detectErrorType(error);
-
-    switch (errorType) {
-        case ErrorTypes.PERMISSION:
-            return formatPermissionError({
-                operation: context.operation || 'access',
-                path: context.path || error.path || ''
-            });
-
-        case ErrorTypes.DISK_FULL:
-            return formatDiskFullError({
-                operation: context.operation || 'write',
-                path: context.path || error.path || ''
-            });
-
-        case ErrorTypes.FILE_LOCKED:
-            return formatFileLockError({
-                path: context.path || error.path || ''
-            });
-
-        case ErrorTypes.NETWORK:
-            return formatNetworkError({
-                url: context.url || '',
-                error
-            });
-
-        case ErrorTypes.CORRUPTED:
-            return formatCorruptedConfigError({
-                configPath: context.configPath || context.path || '',
-                error
-            });
-
-        case ErrorTypes.TIMEOUT:
-            return formatTimeoutError({
-                operation: context.operation || 'Operation',
-                timeoutMs: context.timeoutMs || 30000
-            });
-
-        case ErrorTypes.CONCURRENT_OPERATION:
-            return formatConcurrentOperationError({
-                operation: context.operation || 'this operation',
-                lockHolder: context.lockHolder || 'another process',
-                lockFile: context.lockFile || ''
-            });
-
-        default:
-            // Generic error formatting
-            return [
-                '',
-                chalk.bgRed.white.bold(' Error '),
-                chalk.red('─'.repeat(50)),
-                '',
-                chalk.white(error.message || String(error)),
-                context.path ? chalk.gray(`  Path: ${context.path}`) : '',
-                '',
-                chalk.red('─'.repeat(50)),
-                ''
-            ].filter(Boolean).join('\n');
-    }
-}
-
-/**
- * Wrap an async function with error handling.
- *
- * @param {Function} fn - The async function to wrap
- * @param {Object} context - Context for error messages
- * @returns {Function} - Wrapped function
- */
-export function withErrorHandling(fn, context = {}) {
-    return async (...args) => {
-        try {
-            return await fn(...args);
-        } catch (error) {
-            console.log(formatError(error, context));
-            return { success: false, error: error.message };
-        }
-    };
-}
-
-/**
- * Check if an error is recoverable (can be retried).
- *
- * @param {Error} error - The error to check
- * @returns {boolean} - True if the error might be recoverable with retry
- */
-export function isRecoverableError(error) {
-    const errorType = detectErrorType(error);
-
-    // These error types might succeed if retried
-    return [
-        ErrorTypes.NETWORK,
-        ErrorTypes.TIMEOUT,
-        ErrorTypes.FILE_LOCKED
-    ].includes(errorType);
-}
+/**
+ * Error handling utilities for Iris Vue integration.
+ * Provides user-friendly error messages with actionable solutions.
+ */
+
+import chalk from 'chalk';
+
+/**
+ * Error types for categorization and handling.
+ */
+export const ErrorTypes = {
+    PERMISSION: 'PERMISSION',
+    DISK_FULL: 'DISK_FULL',
+    FILE_LOCKED: 'FILE_LOCKED',
+    NOT_FOUND: 'NOT_FOUND',
+    INVALID_CONFIG: 'INVALID_CONFIG',
+    NETWORK: 'NETWORK',
+    VALIDATION: 'VALIDATION',
+    CONCURRENT_OPERATION: 'CONCURRENT_OPERATION',
+    TIMEOUT: 'TIMEOUT',
+    CORRUPTED: 'CORRUPTED',
+    UNKNOWN: 'UNKNOWN'
+};
+
+/**
+ * Detect the type of error from an Error object or error code.
+ *
+ * @param {Error | string} error - The error to analyze
+ * @returns {string} - One of ErrorTypes
+ */
+export function detectErrorType(error) {
+    const code = error?.code || error;
+    const message = (error?.message || String(error)).toLowerCase();
+
+    // Permission errors
+    if (code === 'EACCES' || code === 'EPERM' || message.includes('permission denied')) {
+        return ErrorTypes.PERMISSION;
+    }
+
+    // Disk full errors
+    if (code === 'ENOSPC' || message.includes('no space left') || message.includes('disk full')) {
+        return ErrorTypes.DISK_FULL;
+    }
+
+    // File locked errors (Windows mainly)
+    if (code === 'EBUSY' || code === 'ENOTEMPTY' || message.includes('resource busy') ||
+        message.includes('being used by another process')) {
+        return ErrorTypes.FILE_LOCKED;
+    }
+
+    // Not found errors
+    if (code === 'ENOENT' || message.includes('no such file') || message.includes('not found')) {
+        return ErrorTypes.NOT_FOUND;
+    }
+
+    // Network errors
+    if (code === 'ENOTFOUND' || code === 'ECONNREFUSED' || code === 'ECONNRESET' ||
+        code === 'ETIMEDOUT' || message.includes('network') || message.includes('fetch')) {
+        return ErrorTypes.NETWORK;
+    }
+
+    // JSON/config parsing errors
+    if (message.includes('json') || message.includes('parse') || message.includes('syntax')) {
+        return ErrorTypes.CORRUPTED;
+    }
+
+    // Timeout errors
+    if (code === 'ETIMEDOUT' || message.includes('timeout')) {
+        return ErrorTypes.TIMEOUT;
+    }
+
+    return ErrorTypes.UNKNOWN;
+}
+
+/**
+ * Format a permission error with helpful guidance.
+ *
+ * @param {Object} options - Error context
+ * @param {string} options.operation - What operation failed (e.g., 'write', 'delete', 'read')
+ * @param {string} options.path - The path that caused the error
+ * @param {string} options.platform - The platform ('win32', 'darwin', 'linux')
+ * @returns {string} - Formatted error message
+ */
+export function formatPermissionError(options) {
+    const { operation = 'access', path = '', platform = process.platform } = options;
+
+    const lines = [
+        '',
+        chalk.bgRed.white.bold(' Permission Error '),
+        chalk.red('─'.repeat(50)),
+        '',
+        chalk.white(`Unable to ${operation} files at:`),
+        chalk.gray(`  ${path}`),
+        '',
+        chalk.cyan('Possible causes:'),
+    ];
+
+    if (platform === 'win32') {
+        lines.push(
+            chalk.gray('  1. File is open in another program (VS Code, Explorer, antivirus)'),
+            chalk.gray('  2. You need to run the command as Administrator'),
+            chalk.gray('  3. The file is marked as read-only'),
+            '',
+            chalk.cyan('Solutions:'),
+            chalk.white('  1. Close any programs that might have the file open'),
+            chalk.white('  2. Run your terminal as Administrator:'),
+            chalk.gray('     Right-click terminal > "Run as administrator"'),
+            chalk.white('  3. Check file properties and uncheck "Read-only"'),
+            chalk.white('  4. Temporarily disable antivirus real-time scanning')
+        );
+    } else {
+        lines.push(
+            chalk.gray('  1. Files are owned by a different user'),
+            chalk.gray('  2. Insufficient permissions on directory'),
+            chalk.gray('  3. File system is mounted read-only'),
+            '',
+            chalk.cyan('Solutions:'),
+            chalk.white('  1. Change ownership of the files:'),
+            chalk.yellow(`     sudo chown -R $(whoami) "${path}"`),
+            chalk.white('  2. Fix directory permissions:'),
+            chalk.yellow(`     chmod -R u+rwX "${path}"`),
+            chalk.white('  3. Use sudo for this operation (if appropriate):'),
+            chalk.yellow('     sudo magentrix <command>')
+        );
+    }
+
+    lines.push('', chalk.red('─'.repeat(50)), '');
+
+    return lines.join('\n');
+}
+
+/**
+ * Format a disk full error with helpful guidance.
+ *
+ * @param {Object} options - Error context
+ * @param {string} options.operation - What operation failed
+ * @param {string} options.path - The path that caused the error
+ * @returns {string} - Formatted error message
+ */
+export function formatDiskFullError(options) {
+    const { operation = 'write', path = '' } = options;
+    const platform = process.platform;
+
+    const lines = [
+        '',
+        chalk.bgRed.white.bold(' Disk Full '),
+        chalk.red('─'.repeat(50)),
+        '',
+        chalk.white(`Cannot ${operation} - no disk space available.`),
+        chalk.gray(`  Path: ${path}`),
+        '',
+        chalk.cyan('Solutions:'),
+    ];
+
+    if (platform === 'win32') {
+        lines.push(
+            chalk.white('  1. Free up disk space:'),
+            chalk.gray('     - Empty the Recycle Bin'),
+            chalk.gray('     - Run Disk Cleanup (cleanmgr.exe)'),
+            chalk.gray('     - Uninstall unused programs'),
+            chalk.white('  2. Clear npm cache:'),
+            chalk.yellow('     npm cache clean --force'),
+            chalk.white('  3. Check available space:'),
+            chalk.yellow('     wmic logicaldisk get size,freespace,caption')
+        );
+    } else {
+        lines.push(
+            chalk.white('  1. Check disk usage:'),
+            chalk.yellow('     df -h'),
+            chalk.white('  2. Find large files:'),
+            chalk.yellow('     du -sh * | sort -rh | head -20'),
+            chalk.white('  3. Clear npm cache:'),
+            chalk.yellow('     npm cache clean --force'),
+            chalk.white('  4. Clear system logs (macOS):'),
+            chalk.yellow('     sudo rm -rf /private/var/log/*'),
+            chalk.white('  5. Clear trash:'),
+            chalk.yellow('     rm -rf ~/.Trash/*')
+        );
+    }
+
+    lines.push('', chalk.red('─'.repeat(50)), '');
+
+    return lines.join('\n');
+}
+
+/**
+ * Format a file locked error with helpful guidance.
+ *
+ * @param {Object} options - Error context
+ * @param {string} options.path - The path that caused the error
+ * @returns {string} - Formatted error message
+ */
+export function formatFileLockError(options) {
+    const { path = '' } = options;
+    const platform = process.platform;
+
+    const lines = [
+        '',
+        chalk.bgYellow.black.bold(' File In Use '),
+        chalk.yellow('─'.repeat(50)),
+        '',
+        chalk.white('Cannot modify file - it is being used by another program.'),
+        chalk.gray(`  Path: ${path}`),
+        '',
+        chalk.cyan('This commonly happens when:'),
+        chalk.gray('  - Your IDE (VS Code, WebStorm) has the file open'),
+        chalk.gray('  - A dev server is running and watching files'),
+        chalk.gray('  - Antivirus is scanning the file'),
+        chalk.gray('  - Another terminal has the directory open'),
+        '',
+        chalk.cyan('Solutions:'),
+    ];
+
+    if (platform === 'win32') {
+        lines.push(
+            chalk.white('  1. Close applications that might be using the file'),
+            chalk.white('  2. Close any Vue/React dev servers running from this project'),
+            chalk.white('  3. Close and reopen VS Code'),
+            chalk.white('  4. Find what is using the file:'),
+            chalk.gray('     - Open Resource Monitor (resmon.exe)'),
+            chalk.gray('     - Go to CPU > Associated Handles'),
+            chalk.gray('     - Search for the filename')
+        );
+    } else {
+        lines.push(
+            chalk.white('  1. Close applications that might be using the file'),
+            chalk.white('  2. Stop any running dev servers'),
+            chalk.white('  3. Find what is using the file:'),
+            chalk.yellow(`     lsof "${path}"`),
+            chalk.white('  4. Wait a few seconds and try again')
+        );
+    }
+
+    lines.push('', chalk.yellow('─'.repeat(50)), '');
+
+    return lines.join('\n');
+}
+
+/**
+ * Format a network error with helpful guidance.
+ *
+ * @param {Object} options - Error context
+ * @param {string} options.url - The URL that failed
+ * @param {Error} options.error - The original error
+ * @returns {string} - Formatted error message
+ */
+export function formatNetworkError(options) {
+    const { url = '', error } = options;
+    const code = error?.code || '';
+    const message = error?.message || '';
+
+    const lines = [
+        '',
+        chalk.bgRed.white.bold(' Network Error '),
+        chalk.red('─'.repeat(50)),
+        '',
+        chalk.white('Failed to connect to the server.'),
+        chalk.gray(`  URL: ${url}`),
+        chalk.gray(`  Error: ${message}`),
+        '',
+        chalk.cyan('Possible causes:'),
+    ];
+
+    if (code === 'ENOTFOUND' || message.includes('getaddrinfo')) {
+        lines.push(
+            chalk.gray('  - The server hostname could not be resolved'),
+            chalk.gray('  - DNS server issues'),
+            chalk.gray('  - Typo in the URL'),
+            '',
+            chalk.cyan('Solutions:'),
+            chalk.white('  1. Check that the URL is correct'),
+            chalk.white('  2. Verify your internet connection'),
+            chalk.white('  3. Try accessing the URL in a browser')
+        );
+    } else if (code === 'ECONNREFUSED') {
+        lines.push(
+            chalk.gray('  - The server is not running'),
+            chalk.gray('  - Wrong port number'),
+            chalk.gray('  - Firewall blocking the connection'),
+            '',
+            chalk.cyan('Solutions:'),
+            chalk.white('  1. Verify the server is running'),
+            chalk.white('  2. Check if the URL and port are correct'),
+            chalk.white('  3. Check firewall settings')
+        );
+    } else if (code === 'ETIMEDOUT' || message.includes('timeout')) {
+        lines.push(
+            chalk.gray('  - Server took too long to respond'),
+            chalk.gray('  - Network congestion'),
+            chalk.gray('  - Server might be overloaded'),
+            '',
+            chalk.cyan('Solutions:'),
+            chalk.white('  1. Wait a moment and try again'),
+            chalk.white('  2. Check if you can access the server in a browser'),
+            chalk.white('  3. Try from a different network')
+        );
+    } else {
+        lines.push(
+            chalk.gray('  - Network connectivity issues'),
+            chalk.gray('  - Server is unreachable'),
+            '',
+            chalk.cyan('Solutions:'),
+            chalk.white('  1. Check your internet connection'),
+            chalk.white('  2. Try again in a few minutes'),
+            chalk.white('  3. Verify the URL is correct')
+        );
+    }
+
+    lines.push('', chalk.red('─'.repeat(50)), '');
+
+    return lines.join('\n');
+}
+
+/**
+ * Format a corrupted config error with helpful guidance.
+ *
+ * @param {Object} options - Error context
+ * @param {string} options.configPath - Path to the corrupted config
+ * @param {Error} options.error - The original error
+ * @returns {string} - Formatted error message
+ */
+export function formatCorruptedConfigError(options) {
+    const { configPath = '', error } = options;
+    const message = error?.message || 'Invalid JSON format';
+
+    const lines = [
+        '',
+        chalk.bgRed.white.bold(' Config File Corrupted '),
+        chalk.red('─'.repeat(50)),
+        '',
+        chalk.white('The configuration file could not be read due to invalid format.'),
+        chalk.gray(`  Path: ${configPath}`),
+        chalk.gray(`  Error: ${message}`),
+        '',
+        chalk.cyan('This can happen when:'),
+        chalk.gray('  - A previous write was interrupted'),
+        chalk.gray('  - The file was manually edited with invalid JSON'),
+        chalk.gray('  - Disk errors corrupted the file'),
+        '',
+        chalk.cyan('Solutions:'),
+        chalk.white('  1. Check if a backup exists:'),
+        chalk.yellow(`     ls -la "${configPath}.bak"`),
+        chalk.white('  2. If backup exists, restore it:'),
+        chalk.yellow(`     cp "${configPath}.bak" "${configPath}"`),
+        chalk.white('  3. If no backup, you may need to delete and recreate:'),
+        chalk.yellow(`     rm "${configPath}"`),
+        chalk.gray('     Then re-run your command to regenerate the config.'),
+        '',
+        chalk.bgYellow.black(' Warning '),
+        chalk.yellow('  Deleting the config will lose your linked project history.'),
+        chalk.yellow('  You will need to re-link your Vue projects.'),
+        '',
+        chalk.red('─'.repeat(50)),
+        ''
+    ];
+
+    return lines.join('\n');
+}
+
+/**
+ * Format a concurrent operation error with helpful guidance.
+ *
+ * @param {Object} options - Error context
+ * @param {string} options.operation - The operation that was blocked
+ * @param {string} options.lockHolder - Description of what holds the lock
+ * @param {string} options.lockFile - Path to the lock file
+ * @returns {string} - Formatted error message
+ */
+export function formatConcurrentOperationError(options) {
+    const { operation = 'this operation', lockHolder = 'another process', lockFile = '' } = options;
+
+    const lines = [
+        '',
+        chalk.bgYellow.black.bold(' Operation Blocked '),
+        chalk.yellow('─'.repeat(50)),
+        '',
+        chalk.white(`Cannot ${operation} - ${lockHolder} is currently running.`),
+        '',
+        chalk.cyan('Why this happens:'),
+        chalk.gray('  Running multiple operations simultaneously can cause:'),
+        chalk.gray('  - File corruption'),
+        chalk.gray('  - Data loss'),
+        chalk.gray('  - Inconsistent state'),
+        '',
+        chalk.cyan('Solutions:'),
+        chalk.white('  1. Wait for the other operation to complete'),
+        chalk.white('  2. If the other operation crashed, remove the lock file:'),
+        lockFile ? chalk.yellow(`     rm "${lockFile}"`) : chalk.gray('     (lock file path not available)'),
+        chalk.white('  3. Check for running magentrix processes:'),
+        chalk.yellow('     ps aux | grep magentrix'),
+        '',
+        chalk.yellow('─'.repeat(50)),
+        ''
+    ];
+
+    return lines.join('\n');
+}
+
+/**
+ * Format a timeout error with helpful guidance.
+ *
+ * @param {Object} options - Error context
+ * @param {string} options.operation - What operation timed out
+ * @param {number} options.timeoutMs - The timeout value in milliseconds
+ * @returns {string} - Formatted error message
+ */
+export function formatTimeoutError(options) {
+    const { operation = 'Operation', timeoutMs = 0 } = options;
+    const seconds = Math.round(timeoutMs / 1000);
+
+    const lines = [
+        '',
+        chalk.bgYellow.black.bold(' Operation Timed Out '),
+        chalk.yellow('─'.repeat(50)),
+        '',
+        chalk.white(`${operation} did not complete within ${seconds} seconds.`),
+        '',
+        chalk.cyan('Possible causes:'),
+        chalk.gray('  - The server is slow or unresponsive'),
+        chalk.gray('  - Network latency is high'),
+        chalk.gray('  - Large amount of data being processed'),
+        '',
+        chalk.cyan('Solutions:'),
+        chalk.white('  1. Try running the command again'),
+        chalk.white('  2. Check your network connection'),
+        chalk.white('  3. If working with large files, allow more time'),
+        '',
+        chalk.yellow('─'.repeat(50)),
+        ''
+    ];
+
+    return lines.join('\n');
+}
+
+/**
+ * Format any error with automatic type detection.
+ *
+ * @param {Error} error - The error to format
+ * @param {Object} context - Additional context for the error
+ * @returns {string} - Formatted error message
+ */
+export function formatError(error, context = {}) {
+    const errorType = detectErrorType(error);
+
+    switch (errorType) {
+        case ErrorTypes.PERMISSION:
+            return formatPermissionError({
+                operation: context.operation || 'access',
+                path: context.path || error.path || ''
+            });
+
+        case ErrorTypes.DISK_FULL:
+            return formatDiskFullError({
+                operation: context.operation || 'write',
+                path: context.path || error.path || ''
+            });
+
+        case ErrorTypes.FILE_LOCKED:
+            return formatFileLockError({
+                path: context.path || error.path || ''
+            });
+
+        case ErrorTypes.NETWORK:
+            return formatNetworkError({
+                url: context.url || '',
+                error
+            });
+
+        case ErrorTypes.CORRUPTED:
+            return formatCorruptedConfigError({
+                configPath: context.configPath || context.path || '',
+                error
+            });
+
+        case ErrorTypes.TIMEOUT:
+            return formatTimeoutError({
+                operation: context.operation || 'Operation',
+                timeoutMs: context.timeoutMs || 30000
+            });
+
+        case ErrorTypes.CONCURRENT_OPERATION:
+            return formatConcurrentOperationError({
+                operation: context.operation || 'this operation',
+                lockHolder: context.lockHolder || 'another process',
+                lockFile: context.lockFile || ''
+            });
+
+        default:
+            // Generic error formatting
+            return [
+                '',
+                chalk.bgRed.white.bold(' Error '),
+                chalk.red('─'.repeat(50)),
+                '',
+                chalk.white(error.message || String(error)),
+                context.path ? chalk.gray(`  Path: ${context.path}`) : '',
+                '',
+                chalk.red('─'.repeat(50)),
+                ''
+            ].filter(Boolean).join('\n');
+    }
+}
+
+/**
+ * Wrap an async function with error handling.
+ *
+ * @param {Function} fn - The async function to wrap
+ * @param {Object} context - Context for error messages
+ * @returns {Function} - Wrapped function
+ */
+export function withErrorHandling(fn, context = {}) {
+    return async (...args) => {
+        try {
+            return await fn(...args);
+        } catch (error) {
+            console.log(formatError(error, context));
+            return { success: false, error: error.message };
+        }
+    };
+}
+
+/**
+ * Check if an error is recoverable (can be retried).
+ *
+ * @param {Error} error - The error to check
+ * @returns {boolean} - True if the error might be recoverable with retry
+ */
+export function isRecoverableError(error) {
+    const errorType = detectErrorType(error);
+
+    // These error types might succeed if retried
+    return [
+        ErrorTypes.NETWORK,
+        ErrorTypes.TIMEOUT,
+        ErrorTypes.FILE_LOCKED
+    ].includes(errorType);
+}