@magentrix-corp/magentrix-cli 1.3.9 → 1.3.11

package/README.md

@@ -573,7 +573,7 @@ Your Vue project needs two configuration files:
 ```typescript
 // src/config.ts
 export const config = {
-  appPath: "my-app",           // Required: App identifier (folder name on server)
+  appSlug: "my-app",           // Required: App identifier (folder name on server)
   appName: "My Application",   // Required: Display name in navigation menu
   appDescription: "",          // Optional: App description
   appIconId: "",               // Optional: App icon ID
@@ -589,11 +589,43 @@ VITE_ASSETS = '[]'  # Injected automatically by vue-run-dev
 ```
 
 **Accepted field names in config.ts:**
-- Slug: `appPath`, `slug`, or `app_path`
+- Slug: `appSlug`, `slug`, or `app_slug`
 - Name: `appName`, `app_name`, or `name`
 - Description: `appDescription` or `app_description`
 - Icon: `appIconId` or `app_icon_id`
 
+#### Changing an App Slug
+
+> **⚠️ Important:** Changing the `appSlug`/`slug` in `config.ts` creates a **new** Iris app on Magentrix. The old app is **not** automatically deleted.
+
+If you simply change the slug and run `vue-run-build`, you'll end up with two apps on the server - the old one becomes orphaned.
+
+**Recommended workflow for changing an app slug:**
+
+```bash
+# 1. Delete the old app first (from Magentrix workspace)
+cd ~/magentrix-workspace
+magentrix iris-app-delete         # Select the old app, confirm deletion
+                                  # This removes it from server, local files, and cache
+                                  # Optionally unlink the Vue project when prompted
+
+# 2. Change the slug in your Vue project
+cd ~/my-vue-app
+# Edit config.ts: change appSlug from "old-slug" to "new-slug"
+
+# 3. Re-link the project with the new slug
+magentrix iris-app-link           # Updates the linked project with new slug
+
+# 4. Build, stage, and publish
+magentrix vue-run-build           # Stages to new folder: src/iris-apps/new-slug/
+# When prompted, choose to publish
+```
+
+**What happens if you don't follow this workflow:**
+- Both `old-slug` and `new-slug` apps will exist on the server
+- The old app remains in `src/iris-apps/old-slug/` locally
+- You'll need to manually delete the old app using `magentrix iris-app-delete`
+
 ### Command Availability
 
 **In Vue project directories** (detected by presence of `config.ts`):
@@ -693,8 +725,8 @@ When running `vue-run-build` from a Vue project, the CLI checks if the target wo
 2. Pull latest changes: `magentrix pull`
 3. Re-run `vue-run-build` from your Vue project
 
-#### "Missing required field in config.ts: slug (appPath)"
-Your Vue project's `config.ts` is missing the app identifier. Add an `appPath` or `slug` field.
+#### "Missing required field in config.ts: slug (appSlug)"
+Your Vue project's `config.ts` is missing the app identifier. Add an `appSlug` or `slug` field.
 
 #### "Missing required field in config.ts: appName"
 Your Vue project's `config.ts` is missing the display name. Add an `appName` field.
@@ -743,6 +775,12 @@ magentrix publish              # Sync to server
 #### Changes not detected after vue-run-build
 The CLI uses content hash tracking to detect changes. If you rebuild without changes, `magentrix publish` will show "All files are in sync — nothing to publish!" This is expected behavior and saves unnecessary uploads.
 
+#### Duplicate apps after changing slug
+If you changed the `appSlug`/`slug` in `config.ts` and now have two apps on the server:
+1. The old app is orphaned and needs manual cleanup
+2. Run `magentrix iris-app-delete` and select the old app to remove it
+3. See [Changing an App Slug](#changing-an-app-slug) for the proper workflow
+
 ---
 
 ## Handling Conflicts

package/actions/iris/buildStage.js

@@ -27,9 +27,33 @@ import {
 } from '../../utils/iris/linker.js';
 import { EXPORT_ROOT, IRIS_APPS_DIR, HASHED_CWD } from '../../vars/global.js';
 import { getValidWorkspaces } from '../../utils/workspaces.js';
+import { formatTimeoutError } from '../../utils/iris/errors.js';
 
 const config = new Config();
 
+/**
+ * Timeout for status check operations (30 seconds).
+ */
+const STATUS_CHECK_TIMEOUT = 30000;
+
+/**
+ * Timeout for command execution (5 minutes).
+ */
+const COMMAND_TIMEOUT = 5 * 60 * 1000;
+
+/**
+ * Display warnings from build/stage operations.
+ *
+ * @param {string[]} warnings - Array of warning messages
+ */
+function displayWarnings(warnings) {
+    if (!warnings || warnings.length === 0) return;
+
+    for (const warning of warnings) {
+        console.log(chalk.yellow(`⚠ ${warning}`));
+    }
+}
+
 /**
  * Check if the current directory is a Vue project (has config.ts).
  * @returns {boolean}
@@ -221,6 +245,9 @@ export const vueBuildStage = async (options = {}) => {
         console.log(chalk.green(`\u2713 Build completed successfully`));
         console.log(chalk.gray(`  Output: ${distPath}`));
 
+        // Display any build warnings
+        displayWarnings(buildResult.warnings);
+
         // Validate build output
         const validation = validateIrisBuild(distPath);
         if (!validation.valid) {
@@ -245,6 +272,9 @@ export const vueBuildStage = async (options = {}) => {
 
     console.log(chalk.green(`\u2713 Staged ${stageResult.fileCount} files to ${stageResult.stagedPath}`));
 
+    // Display any staging warnings
+    displayWarnings(stageResult.warnings);
+
     // Summary
     console.log();
     console.log(chalk.green('─'.repeat(48)));
@@ -387,6 +417,9 @@ async function buildFromVueProject(options) {
         console.log(chalk.green(`\u2713 Build completed successfully`));
         console.log(chalk.gray(`  Output: ${distPath}`));
 
+        // Display any build warnings
+        displayWarnings(buildResult.warnings);
+
         // Validate build output
         const validation = validateIrisBuild(distPath);
         if (!validation.valid) {
@@ -469,6 +502,9 @@ async function buildFromVueProject(options) {
 
     console.log(chalk.green(`\u2713 Staged ${stageResult.fileCount} files to ${stageResult.stagedPath}`));
 
+    // Display any staging warnings
+    displayWarnings(stageResult.warnings);
+
     // Summary
     console.log();
     console.log(chalk.green('─'.repeat(48)));
@@ -509,7 +545,7 @@ async function buildFromVueProject(options) {
  * Check if a workspace needs to pull (has remote changes or conflicts).
  *
  * @param {string} workspacePath - Path to the Magentrix workspace
- * @returns {Promise<{checked: boolean, needsPull: boolean}>}
+ * @returns {Promise<{checked: boolean, needsPull: boolean, timedOut: boolean}>}
  */
 async function checkWorkspaceSyncStatus(workspacePath) {
     return new Promise((resolvePromise) => {
@@ -517,6 +553,7 @@ async function checkWorkspaceSyncStatus(workspacePath) {
         const npmCmd = isWindows ? 'npx.cmd' : 'npx';
 
         let output = '';
+        let resolved = false;
 
         const child = spawn(npmCmd, ['magentrix', 'status'], {
             cwd: workspacePath,
@@ -524,6 +561,20 @@ async function checkWorkspaceSyncStatus(workspacePath) {
             shell: isWindows
         });
 
+        // Set timeout for status check
+        const timeout = setTimeout(() => {
+            if (!resolved) {
+                resolved = true;
+                try {
+                    child.kill('SIGTERM');
+                } catch {
+                    // Ignore kill errors
+                }
+                console.log(chalk.yellow(`\n⚠ Status check timed out after ${STATUS_CHECK_TIMEOUT / 1000} seconds`));
+                resolvePromise({ checked: false, needsPull: false, timedOut: true });
+            }
+        }, STATUS_CHECK_TIMEOUT);
+
         child.stdout.on('data', (data) => {
             output += data.toString();
         });
@@ -533,6 +584,10 @@ async function checkWorkspaceSyncStatus(workspacePath) {
         });
 
         child.on('close', (code) => {
+            if (resolved) return;
+            resolved = true;
+            clearTimeout(timeout);
+
             // Check output for specific issue indicators from status command
             // Note: We avoid checking for "remote" as it appears in normal output
             // ("Checking local files vs remote Magentrix...")
@@ -552,12 +607,17 @@ async function checkWorkspaceSyncStatus(workspacePath) {
 
             const needsPull = !isInSync && (hasConflict || isOutdated || isAhead || isMissing || hasContentMismatch || hasWarnings);
 
-            resolvePromise({ checked: code === 0, needsPull });
+            resolvePromise({ checked: code === 0, needsPull, timedOut: false });
         });
 
-        child.on('error', () => {
+        child.on('error', (err) => {
+            if (resolved) return;
+            resolved = true;
+            clearTimeout(timeout);
+
             // If we can't check, assume it's fine and let them proceed
-            resolvePromise({ checked: false, needsPull: false });
+            console.log(chalk.yellow(`\n⚠ Could not check sync status: ${err.message}`));
+            resolvePromise({ checked: false, needsPull: false, timedOut: false });
         });
     });
 }
@@ -567,24 +627,52 @@ async function checkWorkspaceSyncStatus(workspacePath) {
  *
  * @param {string} workspacePath - Path to the Magentrix workspace
  * @param {string} command - The magentrix command to run (e.g., 'pull', 'publish')
+ * @param {number} timeout - Optional timeout in milliseconds (defaults to COMMAND_TIMEOUT)
  * @returns {Promise<boolean>} - True if command succeeded
  */
-async function runCommandFromWorkspace(workspacePath, command) {
+async function runCommandFromWorkspace(workspacePath, command, timeout = COMMAND_TIMEOUT) {
     return new Promise((resolvePromise) => {
         const isWindows = process.platform === 'win32';
         const npmCmd = isWindows ? 'npx.cmd' : 'npx';
 
+        let resolved = false;
+
         const child = spawn(npmCmd, ['magentrix', command], {
             cwd: workspacePath,
             stdio: 'inherit',
             shell: isWindows
         });
 
+        // Set timeout for command execution
+        const timeoutId = setTimeout(() => {
+            if (!resolved) {
+                resolved = true;
+                try {
+                    child.kill('SIGTERM');
+                } catch {
+                    // Ignore kill errors
+                }
+                console.log();
+                console.log(chalk.red(formatTimeoutError({
+                    operation: `magentrix ${command}`,
+                    timeout: timeout,
+                    suggestion: `The ${command} operation is taking too long. Check your network connection or try again later.`
+                })));
+                resolvePromise(false);
+            }
+        }, timeout);
+
         child.on('close', (code) => {
+            if (resolved) return;
+            resolved = true;
+            clearTimeout(timeoutId);
             resolvePromise(code === 0);
         });
 
         child.on('error', (err) => {
+            if (resolved) return;
+            resolved = true;
+            clearTimeout(timeoutId);
             console.log(chalk.yellow(`Warning: Could not run ${command}: ${err.message}`));
             resolvePromise(false);
         });

package/actions/iris/delete.js

@@ -8,6 +8,8 @@ import { getLinkedProjects, unlinkVueProject } from '../../utils/iris/linker.js'
 import { deleteIrisAppFromServer, deleteLocalIrisAppFiles } from '../../utils/iris/deleteHelper.js';
 import { showPermissionError } from '../../utils/permissionError.js';
 import { EXPORT_ROOT, IRIS_APPS_DIR } from '../../vars/global.js';
+import { acquireLock, releaseLock, LockTypes } from '../../utils/iris/lock.js';
+import { formatFileLockError } from '../../utils/iris/errors.js';
 
 const config = new Config();
 
@@ -99,6 +101,42 @@ export const irisDelete = async () => {
         return;
     }
 
+    // Acquire delete lock to prevent concurrent deletions
+    const lockBasePath = path.join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.magentrix-locks');
+    const lockResult = acquireLock(LockTypes.DELETE, {
+        context: slug,
+        operation: `deleting ${slug}`,
+        basePath: lockBasePath
+    });
+
+    // Track if lock was acquired (permission errors are non-fatal for delete)
+    let lockAcquired = lockResult.acquired;
+    if (!lockResult.acquired) {
+        if (lockResult.error?.includes('permission') || lockResult.error?.includes('EACCES')) {
+            console.log(chalk.yellow('Warning: Could not create delete lock (permission issue). Proceeding without lock.'));
+            lockAcquired = false;
+        } else {
+            console.log(chalk.red('Cannot delete app:'));
+            console.log(chalk.yellow(lockResult.error));
+            return;
+        }
+    }
+
+    try {
+        await performDelete(slug, appName);
+    } finally {
+        if (lockAcquired) {
+            releaseLock(LockTypes.DELETE, { context: slug, basePath: lockBasePath });
+        }
+    }
+};
+
+/**
+ * Perform the actual delete operation.
+ * @param {string} slug - App slug
+ * @param {string} appName - App display name
+ */
+async function performDelete(slug, appName) {
     // Check if app is linked
     const linkedProjects = getLinkedProjects();
     const linkedProject = linkedProjects.find(p => p.slug === slug);
@@ -176,6 +214,13 @@ export const irisDelete = async () => {
         console.log(chalk.gray('Note: The app was deleted from the server and cache.'));
         console.log(chalk.gray('Only local file cleanup failed.'));
         console.log();
+    } else if (localDeleteResult.isFileLocked) {
+        console.log(chalk.yellow('⚠ Could not delete local files - files are in use'));
+        console.log(chalk.gray(localDeleteResult.error));
+        console.log();
+        console.log(chalk.gray('Note: The app was deleted from the server and cache.'));
+        console.log(chalk.gray('Close any programs using these files and delete manually.'));
+        console.log();
     } else {
         console.log(chalk.yellow(`⚠ Failed to delete local files: ${localDeleteResult.error}`));
         console.log(chalk.gray(`Path: ${appPath}`));
@@ -206,6 +251,6 @@ export const irisDelete = async () => {
     console.log(chalk.white(`  Backup saved to: ${chalk.gray(backupResult.backupPath)}`));
     console.log(chalk.white(`  To restore, run: ${chalk.cyan('magentrix iris-app-recover')}`));
     console.log();
-};
+}
 
 export default irisDelete;

package/actions/iris/dev.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import { select, input } from '@inquirer/prompts';
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { resolve, basename, join } from 'node:path';
 import {
     readVueConfig,
     formatMissingConfigError,
@@ -16,6 +16,21 @@ import {
     getLinkedProjectsWithStatus,
     buildProjectChoices
 } from '../../utils/iris/linker.js';
+import {
+    acquireLock,
+    releaseLock,
+    LockTypes,
+    createProjectContext
+} from '../../utils/iris/lock.js';
+import {
+    formatNetworkError,
+    formatError
+} from '../../utils/iris/errors.js';
+
+/**
+ * Timeout for fetching assets (30 seconds).
+ */
+const ASSET_FETCH_TIMEOUT = 30000;
 
 /**
  * vue-run-dev command - Start Vue dev server with platform assets injected.
@@ -95,8 +110,17 @@ export const irisDev = async (options = {}) => {
 
             try {
                 // Get access token using the refresh token from .env.development
-                const tokenData = await getAccessToken(vueConfig.refreshToken, siteUrl);
-                const assetsResult = await getIrisAssets(siteUrl, tokenData.token);
+                // Use Promise.race to implement timeout
+                const tokenPromise = getAccessToken(vueConfig.refreshToken, siteUrl);
+                const timeoutPromise = new Promise((_, reject) =>
+                    setTimeout(() => reject(new Error('Request timed out')), ASSET_FETCH_TIMEOUT)
+                );
+
+                const tokenData = await Promise.race([tokenPromise, timeoutPromise]);
+
+                // Fetch assets with timeout
+                const assetsPromise = getIrisAssets(siteUrl, tokenData.token);
+                const assetsResult = await Promise.race([assetsPromise, timeoutPromise]);
 
                 if (assetsResult.success && assetsResult.assets?.length > 0) {
                     console.log(chalk.green(`\u2713 Found ${assetsResult.assets.length} platform assets`));
@@ -115,7 +139,12 @@ export const irisDev = async (options = {}) => {
                         if (injectResult.success) {
                             console.log(chalk.green(`\u2713 Assets updated in ${injectResult.targetName}`));
                         } else {
-                            console.log(chalk.yellow('Warning: Could not inject assets. Continuing without injection.'));
+                            // Show specific error if available
+                            if (injectResult.error) {
+                                console.log(chalk.yellow(`Warning: Could not inject assets: ${injectResult.error}`));
+                            } else {
+                                console.log(chalk.yellow('Warning: Could not inject assets. Continuing without injection.'));
+                            }
                         }
                     }
                 } else if (assetsResult.error) {
@@ -125,7 +154,23 @@ export const irisDev = async (options = {}) => {
                     console.log(chalk.yellow('No platform assets found.'));
                 }
             } catch (err) {
-                console.log(chalk.yellow(`Warning: Error fetching assets: ${err.message}`));
+                // Provide more helpful error messages based on error type
+                if (err.message === 'Request timed out') {
+                    console.log(chalk.yellow('Warning: Asset fetch timed out.'));
+                    console.log(chalk.gray('Check your network connection or try again later.'));
+                } else if (err.code === 'ENOTFOUND' || err.code === 'ECONNREFUSED' || err.code === 'ETIMEDOUT') {
+                    console.log(chalk.yellow(formatNetworkError({
+                        operation: 'fetch assets',
+                        url: siteUrl,
+                        error: err
+                    })));
+                } else if (err.message?.includes('401') || err.message?.includes('Unauthorized')) {
+                    console.log(chalk.yellow('Warning: Authentication failed.'));
+                    console.log(chalk.gray('Your VITE_REFRESH_TOKEN may be invalid or expired.'));
+                    console.log(chalk.gray('Get a new API key from your Magentrix platform.'));
+                } else {
+                    console.log(chalk.yellow(`Warning: Error fetching assets: ${err.message}`));
+                }
                 console.log(chalk.gray('Continuing without asset injection.'));
             }
         }
@@ -147,8 +192,34 @@ export const irisDev = async (options = {}) => {
 
 /**
  * Run the Vue development server.
+ *
+ * @param {string} projectPath - Path to the Vue project
+ * @returns {Promise<number>} - Exit code
  */
 async function runDevServer(projectPath) {
+    // Acquire dev server lock to prevent multiple instances
+    // Use user home for consistent lock location across projects
+    const lockContext = createProjectContext(projectPath);
+    const lockBasePath = join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.magentrix-locks');
+    const lockResult = acquireLock(LockTypes.DEV_SERVER, {
+        context: lockContext,
+        operation: `dev server for ${basename(projectPath)}`,
+        basePath: lockBasePath
+    });
+
+    // Track if lock was acquired (permission errors are non-fatal)
+    let lockAcquired = lockResult.acquired;
+    if (!lockResult.acquired) {
+        if (lockResult.error?.includes('permission') || lockResult.error?.includes('EACCES')) {
+            console.log(chalk.yellow('Warning: Could not create dev server lock (permission issue). Proceeding without lock.'));
+            lockAcquired = false;
+        } else {
+            console.log(chalk.red('Cannot start dev server:'));
+            console.log(chalk.yellow(lockResult.error));
+            return 1;
+        }
+    }
+
     return new Promise((resolvePromise) => {
         const isWindows = process.platform === 'win32';
         const npmCmd = isWindows ? 'npm.cmd' : 'npm';
@@ -159,16 +230,38 @@ async function runDevServer(projectPath) {
             shell: isWindows  // Windows requires shell: true for .cmd files
         });
 
-        // Handle process signals
-        process.on('SIGINT', () => {
-            child.kill('SIGINT');
-        });
-
-        process.on('SIGTERM', () => {
-            child.kill('SIGTERM');
+        // Cleanup function to release lock
+        const cleanup = () => {
+            if (lockAcquired) {
+                releaseLock(LockTypes.DEV_SERVER, { context: lockContext, basePath: lockBasePath });
+            }
+        };
+
+        // Handle process signals - use once() to avoid memory leaks
+        const handleSignal = (signal) => {
+            cleanup();
+            child.kill(signal);
+            // Give child process a moment to exit, then force exit
+            setTimeout(() => {
+                process.exit(0);
+            }, 500);
+        };
+
+        const sigintHandler = () => handleSignal('SIGINT');
+        const sigtermHandler = () => handleSignal('SIGTERM');
+
+        process.once('SIGINT', sigintHandler);
+        process.once('SIGTERM', sigtermHandler);
+
+        // Remove handlers when child exits to avoid memory leaks
+        child.on('exit', () => {
+            process.removeListener('SIGINT', sigintHandler);
+            process.removeListener('SIGTERM', sigtermHandler);
         });
 
         child.on('close', (code) => {
+            cleanup();
+
             // If dev server exited with error, show helpful context
             if (code !== 0 && code !== null) {
                 console.log();
@@ -184,7 +277,13 @@ async function runDevServer(projectPath) {
                 console.log(chalk.gray('  • Syntax errors in project files'));
                 console.log();
                 console.log(chalk.white('If you see EACCES/permission errors, try:'));
-                console.log(chalk.cyan(`  sudo chown -R $(whoami) "${projectPath}/node_modules"`));
+                if (isWindows) {
+                    console.log(chalk.cyan('  Run terminal as Administrator'));
+                    console.log(chalk.cyan(`  rd /s /q "${projectPath}\\node_modules"`));
+                    console.log(chalk.cyan('  npm install'));
+                } else {
+                    console.log(chalk.cyan(`  sudo chown -R $(whoami) "${projectPath}/node_modules"`));
+                }
                 console.log(chalk.yellow('─'.repeat(48)));
             }
 
@@ -192,7 +291,24 @@ async function runDevServer(projectPath) {
         });
 
         child.on('error', (err) => {
+            cleanup();
             console.log(chalk.red(`Failed to start dev server: ${err.message}`));
+
+            // Provide more specific error messages
+            if (err.code === 'ENOENT') {
+                console.log();
+                console.log(chalk.yellow('npm was not found on your system.'));
+                console.log(chalk.gray('Make sure Node.js is installed and npm is in your PATH.'));
+            } else if (err.code === 'EACCES' || err.code === 'EPERM') {
+                console.log();
+                console.log(chalk.yellow('Permission denied.'));
+                if (isWindows) {
+                    console.log(chalk.gray('Try running the terminal as Administrator.'));
+                } else {
+                    console.log(chalk.gray('Check file permissions for the project directory.'));
+                }
+            }
+
             resolvePromise(1);
         });
     });

package/actions/iris/recover.js

@@ -6,6 +6,7 @@ import { listBackups, restoreIrisApp, deleteBackup } from '../../utils/iris/back
 import { linkVueProject } from '../../utils/iris/linker.js';
 import { showPermissionError } from '../../utils/permissionError.js';
 import { EXPORT_ROOT, IRIS_APPS_DIR } from '../../vars/global.js';
+import { acquireLock, releaseLock, LockTypes } from '../../utils/iris/lock.js';
 
 /**
  * iris-app-recover command - Restore a deleted Iris app from backup.
@@ -135,15 +136,43 @@ export const irisRecover = async (options = {}) => {
         return;
     }
 
-    // Restore files
-    console.log();
-    console.log(chalk.blue('Restoring files...'));
-
-    const restoreResult = await restoreIrisApp(backupPath, {
-        restoreLocal: true,
-        restoreLink: true
+    // Acquire recover lock to prevent concurrent recoveries
+    const lockBasePath = path.join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.magentrix-locks');
+    const lockResult = acquireLock(LockTypes.RECOVER, {
+        context: slug,
+        operation: `recovering ${slug}`,
+        basePath: lockBasePath
     });
 
+    // Track if lock was acquired (permission errors are non-fatal)
+    let lockAcquired = lockResult.acquired;
+    if (!lockResult.acquired) {
+        if (lockResult.error?.includes('permission') || lockResult.error?.includes('EACCES')) {
+            console.log(chalk.yellow('Warning: Could not create recover lock (permission issue). Proceeding without lock.'));
+            lockAcquired = false;
+        } else {
+            console.log(chalk.red('Cannot recover app:'));
+            console.log(chalk.yellow(lockResult.error));
+            return;
+        }
+    }
+
+    let restoreResult;
+    try {
+        // Restore files
+        console.log();
+        console.log(chalk.blue('Restoring files...'));
+
+        restoreResult = await restoreIrisApp(backupPath, {
+            restoreLocal: true,
+            restoreLink: true
+        });
+    } finally {
+        if (lockAcquired) {
+            releaseLock(LockTypes.RECOVER, { context: slug, basePath: lockBasePath });
+        }
+    }
+
     if (!restoreResult.success) {
         if (restoreResult.isPermissionError) {
             const targetDir = path.join(process.cwd(), EXPORT_ROOT, IRIS_APPS_DIR);
@@ -153,6 +182,17 @@ export const irisRecover = async (options = {}) => {
                 backupPath,
                 slug
             });
+        } else if (restoreResult.isFileLocked) {
+            console.log(chalk.red('Cannot restore - files are in use'));
+            console.log(chalk.yellow(restoreResult.error));
+            console.log();
+            console.log(chalk.gray('Close any programs that may be using these files and try again.'));
+        } else if (restoreResult.isCorrupted) {
+            console.log(chalk.red('Backup appears to be corrupted'));
+            console.log(chalk.yellow(restoreResult.error));
+            console.log();
+            console.log(chalk.gray('The backup file may have been damaged. You may need to delete it.'));
+            console.log(chalk.gray(`Backup path: ${backupPath}`));
         } else {
             console.log(chalk.red(`Failed to restore: ${restoreResult.error}`));
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magentrix-corp/magentrix-cli",
-  "version": "1.3.9",
+  "version": "1.3.11",
   "description": "CLI tool for synchronizing local files with Magentrix cloud platform",
   "main": "index.js",
   "type": "module",