@magentrix-corp/magentrix-cli 1.2.0 → 1.3.0

package/actions/pull.js

@@ -5,16 +5,18 @@ import fs from "fs";
 import { withSpinner } from "../utils/spinner.js";
 import { ProgressTracker } from "../utils/progress.js";
 import { createLogger, Logger } from "../utils/logger.js";
-import { EXPORT_ROOT, TYPE_DIR_MAP } from "../vars/global.js";
+import { EXPORT_ROOT, TYPE_DIR_MAP, IRIS_APPS_DIR } from "../vars/global.js";
 import { mapRecordToFile, writeRecords } from "../utils/cli/writeRecords.js";
-import { updateBase, removeFromBase } from "../utils/updateFileBase.js";
+import { updateBase, removeFromBase, removeFromBaseBulk } from "../utils/updateFileBase.js";
 import { compareAllFilesAndLogStatus, promptConflictResolution, showCurrentConflicts } from "../utils/cli/helpers/compare.js";
 import path from "path";
 import { compareLocalAndRemote } from "../utils/compare.js";
 import chalk from 'chalk';
-import { getFileTag } from "../utils/filetag.js";
+import { getFileTag, setFileTag } from "../utils/filetag.js";
 import { downloadAssetsZip, listAssets } from "../utils/magentrix/api/assets.js";
 import { downloadAssets, walkAssets } from "../utils/downloadAssets.js";
+import { listApps, downloadApp } from "../utils/magentrix/api/iris.js";
+import { extractIrisZip, hashIrisAppFolder } from "../utils/iris/zipper.js";
 import { v4 as uuidv4 } from 'uuid';
 import readlineSync from 'readline-sync';
 
@@ -55,6 +57,7 @@ export const pull = async () => {
     progress.addStep('load', 'Loading cached data...');
     progress.addStep('download-code', 'Downloading code entities...', { hasProgress: true });
     progress.addStep('download-assets', 'Downloading static assets...', { hasProgress: true });
+    progress.addStep('download-iris', 'Downloading Iris apps...', { hasProgress: true });
     progress.addStep('process', 'Processing files...', { hasProgress: true });
     progress.addStep('conflicts', 'Checking for conflicts...');
     progress.addStep('write', 'Writing files...', { hasProgress: true });
@@ -72,380 +75,567 @@ export const pull = async () => {
         const instanceChanged = lastInstanceUrl && lastInstanceUrl !== instanceUrl;
 
         if (instanceChanged) {
-        progress.stopSpinner();
-        progress.render();
-        console.log(chalk.yellow.bold(`\n⚠️  INSTANCE CHANGE DETECTED`));
-        console.log(chalk.yellow(`Previous instance: ${chalk.cyan(lastInstanceUrl)}`));
-        console.log(chalk.yellow(`New instance:      ${chalk.cyan(instanceUrl)}`));
-        console.log();
-        console.log(chalk.red.bold(`⚠️  WARNING: This will DELETE your existing ${chalk.white(EXPORT_ROOT + '/')} directory!`));
-        console.log(chalk.gray(`This is necessary to prevent mixing files from different instances.`));
-        console.log();
-
-        const confirm = readlineSync.question(
-            chalk.yellow(`Type ${chalk.white.bold('yes')} to continue and delete ${EXPORT_ROOT}/, or ${chalk.white.bold('no')} to cancel: `)
-        );
+            progress.stopSpinner();
+            progress.render();
+            console.log(chalk.yellow.bold(`\n⚠️  INSTANCE CHANGE DETECTED`));
+            console.log(chalk.yellow(`Previous instance: ${chalk.cyan(lastInstanceUrl)}`));
+            console.log(chalk.yellow(`New instance:      ${chalk.cyan(instanceUrl)}`));
+            console.log();
+            console.log(chalk.red.bold(`⚠️  WARNING: This will DELETE your existing ${chalk.white(EXPORT_ROOT + '/')} directory!`));
+            console.log(chalk.gray(`This is necessary to prevent mixing files from different instances.`));
+            console.log();
+
+            const confirm = readlineSync.question(
+                chalk.yellow(`Type ${chalk.white.bold('yes')} to continue and delete ${EXPORT_ROOT}/, or ${chalk.white.bold('no')} to cancel: `)
+            );
+
+            if (confirm.trim().toLowerCase() !== 'yes') {
+                console.log(chalk.red('\n❌ Pull cancelled. No files were deleted.'));
+                console.log(chalk.gray(`Tip: To pull from ${chalk.cyan(lastInstanceUrl)}, switch back to those credentials.`));
+                process.exit(0);
+            }
 
-        if (confirm.trim().toLowerCase() !== 'yes') {
-            console.log(chalk.red('\n❌ Pull cancelled. No files were deleted.'));
-            console.log(chalk.gray(`Tip: To pull from ${chalk.cyan(lastInstanceUrl)}, switch back to those credentials.`));
-            process.exit(0);
+            console.log(chalk.yellow(`\n🗑️  Removing existing ${EXPORT_ROOT}/ directory...`));
+            if (fs.existsSync(EXPORT_ROOT)) {
+                fs.rmSync(EXPORT_ROOT, { recursive: true, force: true });
+            }
+            // Clear the base.json cache as well since it's from a different instance
+            fs.writeFileSync('.magentrix/base.json', JSON.stringify({}));
+            config.save('cachedFiles', {}, { filename: 'fileCache.json' });
+            config.save('trackedFileTags', {}, { filename: 'fileIdIndex.json' });
+            console.log(chalk.green(`✓ Removed ${EXPORT_ROOT}/ directory\n`));
+
+            progress.start(); // Restart progress tracker
+            progress.startStep('check');
         }
 
-        console.log(chalk.yellow(`\n🗑️  Removing existing ${EXPORT_ROOT}/ directory...`));
-        if (fs.existsSync(EXPORT_ROOT)) {
-            fs.rmSync(EXPORT_ROOT, { recursive: true, force: true });
+        // Save the current instance URL for future comparisons
+        config.save('lastInstanceUrl', instanceUrl, { global: false, filename: 'config.json' });
+        progress.completeStep('check', instanceChanged ? '✓ Instance reset' : '✓ Instance verified');
+
+        // Step 3: Prepare queries for both ActiveClass and ActivePage
+        const queries = [
+            {
+                name: "ActiveClass",
+                query: "SELECT Id,Body,Name,CreatedOn,Description,ModifiedOn,Type FROM ActiveClass",
+                contentField: "Body",
+            },
+            {
+                name: "ActivePage",
+                query: "SELECT Id,Content,Name,CreatedOn,Description,ModifiedOn,Type FROM ActivePage",
+                contentField: "Content",
+            }
+        ];
+
+        // Step 3: Load existing base.json to detect deletions
+        progress.startStep('load');
+        const hits = await config.searchObject({}, { filename: "base.json", global: false });
+        const cachedResults = hits?.[0]?.value || {};
+        const cachedAssets = Object.values(cachedResults).filter(c =>
+            c.type === 'File' || c.type === 'Folder'
+        );
+        progress.completeStep('load', `✓ Loaded ${Object.keys(cachedResults).length} cached entries`);
+
+        // Step 4a: Download code entities (ActiveClass and ActivePage)
+        progress.startStep('download-code');
+
+        let activeClassResult, activePageResult;
+        const codeDownloadErrors = [];
+
+        try {
+            logger.info('Starting code entity downloads');
+            const meqlResults = await Promise.all(
+                queries.map(q => meqlQuery(instanceUrl, token.value, q.query))
+            );
+
+            [activeClassResult, activePageResult] = meqlResults;
+            const totalCodeEntities = activeClassResult.Records.length + activePageResult.Records.length;
+
+            logger.info(`Downloaded ${totalCodeEntities} code entities`, {
+                activeClass: activeClassResult.Records.length,
+                activePage: activePageResult.Records.length
+            });
+
+            progress.updateProgress('download-code', totalCodeEntities, totalCodeEntities, `Downloaded ${totalCodeEntities} code entities`);
+            progress.completeStep('download-code', `✓ Downloaded ${totalCodeEntities} code entities`);
+        } catch (error) {
+            logger.error('Error downloading code entities', error);
+            codeDownloadErrors.push({ stage: 'code-download', error: error.message });
+            progress.failStep('download-code', error.message);
+
+            // Show error preview
+            progress.stopSpinner();
+            console.log('');
+            console.log(chalk.red.bold('❌ Code Download Error:'));
+            console.log(chalk.red(`   ${error.message.substring(0, 200)}`));
+            console.log(chalk.cyan(`\n  📄 Full details in log file`));
+            console.log('');
+
+            // Initialize empty data structures
+            if (!activeClassResult) activeClassResult = { Records: [] };
+            if (!activePageResult) activePageResult = { Records: [] };
+
+            // Restart progress for next step
+            progress.start();
+            progress.startStep('download-assets');
         }
-        // Clear the base.json cache as well since it's from a different instance
-        fs.writeFileSync('.magentrix/base.json', JSON.stringify({}));
-        config.save('cachedFiles', {}, { filename: 'fileCache.json' });
-        config.save('trackedFileTags', {}, { filename: 'fileIdIndex.json' });
-        console.log(chalk.green(`✓ Removed ${EXPORT_ROOT}/ directory\n`));
 
-        progress.start(); // Restart progress tracker
-        progress.startStep('check');
-    }
-
-    // Save the current instance URL for future comparisons
-    config.save('lastInstanceUrl', instanceUrl, { global: false, filename: 'config.json' });
-    progress.completeStep('check', instanceChanged ? '✓ Instance reset' : '✓ Instance verified');
-
-    // Step 3: Prepare queries for both ActiveClass and ActivePage
-    const queries = [
-        {
-            name: "ActiveClass",
-            query: "SELECT Id,Body,Name,CreatedOn,Description,ModifiedOn,Type FROM ActiveClass",
-            contentField: "Body",
-        },
-        {
-            name: "ActivePage",
-            query: "SELECT Id,Content,Name,CreatedOn,Description,ModifiedOn,Type FROM ActivePage",
-            contentField: "Content",
+        // Step 4b: Download static assets
+        if (!codeDownloadErrors.length) {
+            progress.startStep('download-assets');
         }
-    ];
-
-    // Step 3: Load existing base.json to detect deletions
-    progress.startStep('load');
-    const hits = await config.searchObject({}, { filename: "base.json", global: false });
-    const cachedResults = hits?.[0]?.value || {};
-    const cachedAssets = Object.values(cachedResults).filter(c =>
-        c.type === 'File' || c.type === 'Folder'
-    );
-    progress.completeStep('load', `✓ Loaded ${Object.keys(cachedResults).length} cached entries`);
-
-    // Step 4a: Download code entities (ActiveClass and ActivePage)
-    progress.startStep('download-code');
-
-    let activeClassResult, activePageResult;
-    const codeDownloadErrors = [];
-
-    try {
-        logger.info('Starting code entity downloads');
-        const meqlResults = await Promise.all(
-            queries.map(q => meqlQuery(instanceUrl, token.value, q.query))
-        );
-
-        [activeClassResult, activePageResult] = meqlResults;
-        const totalCodeEntities = activeClassResult.Records.length + activePageResult.Records.length;
-
-        logger.info(`Downloaded ${totalCodeEntities} code entities`, {
-            activeClass: activeClassResult.Records.length,
-            activePage: activePageResult.Records.length
-        });
-
-        progress.updateProgress('download-code', totalCodeEntities, totalCodeEntities, `Downloaded ${totalCodeEntities} code entities`);
-        progress.completeStep('download-code', `✓ Downloaded ${totalCodeEntities} code entities`);
-    } catch (error) {
-        logger.error('Error downloading code entities', error);
-        codeDownloadErrors.push({ stage: 'code-download', error: error.message });
-        progress.failStep('download-code', error.message);
 
-        // Show error preview
-        progress.stopSpinner();
-        console.log('');
-        console.log(chalk.red.bold('❌ Code Download Error:'));
-        console.log(chalk.red(`   ${error.message.substring(0, 200)}`));
-        console.log(chalk.cyan(`\n  📄 Full details in log file`));
-        console.log('');
-
-        // Initialize empty data structures
-        if (!activeClassResult) activeClassResult = { Records: [] };
-        if (!activePageResult) activePageResult = { Records: [] };
-
-        // Restart progress for next step
-        progress.start();
-        progress.startStep('download-assets');
-    }
+        let assets;
+        const assetDownloadErrors = [];
+
+        try {
+            logger.info('Starting static asset downloads');
+            assets = await downloadAssets(instanceUrl, token.value, null, (current, total, message) => {
+                progress.updateProgress('download-assets', current, total, message);
+            }, logger);
+
+            logger.info(`Downloaded ${assets.tree.length} asset folders`);
+            progress.completeStep('download-assets', `✓ Downloaded ${assets.tree.length} asset folders`);
+        } catch (error) {
+            logger.error('Error downloading static assets', error);
+            assetDownloadErrors.push({ stage: 'asset-download', error: error.message });
+            progress.failStep('download-assets', error.message);
+
+            // Show error preview
+            progress.stopSpinner();
+            console.log('');
+            console.log(chalk.red.bold('❌ Asset Download Error:'));
+            console.log(chalk.red(`   ${error.message.substring(0, 200)}`));
+            console.log(chalk.cyan(`\n  📄 Full details in log file`));
+            console.log('');
+
+            // Initialize empty data structure
+            if (!assets) assets = { tree: [] };
+
+            // Restart progress for next step
+            progress.start();
+        }
 
-    // Step 4b: Download static assets
-    if (!codeDownloadErrors.length) {
-        progress.startStep('download-assets');
-    }
+        // Step 4c: Download Iris apps
+        progress.startStep('download-iris');
+        let irisApps = [];
+        const irisDownloadErrors = [];
 
-    let assets;
-    const assetDownloadErrors = [];
+        try {
+            logger.info('Fetching Iris apps list');
+            const irisListResult = await listApps(instanceUrl, token.value);
 
-    try {
-        logger.info('Starting static asset downloads');
-        assets = await downloadAssets(instanceUrl, token.value, null, (current, total, message) => {
-            progress.updateProgress('download-assets', current, total, message);
-        }, logger);
+            if (irisListResult.success && irisListResult.apps && irisListResult.apps.length > 0) {
+                irisApps = irisListResult.apps;
+                const irisAppsDir = path.resolve(EXPORT_ROOT, IRIS_APPS_DIR);
 
-        logger.info(`Downloaded ${assets.tree.length} asset folders`);
-        progress.completeStep('download-assets', `✓ Downloaded ${assets.tree.length} asset folders`);
-    } catch (error) {
-        logger.error('Error downloading static assets', error);
-        assetDownloadErrors.push({ stage: 'asset-download', error: error.message });
-        progress.failStep('download-assets', error.message);
+                // Ensure iris-apps directory exists
+                if (!fs.existsSync(irisAppsDir)) {
+                    fs.mkdirSync(irisAppsDir, { recursive: true });
+                }
 
-        // Show error preview
-        progress.stopSpinner();
-        console.log('');
-        console.log(chalk.red.bold('❌ Asset Download Error:'));
-        console.log(chalk.red(`   ${error.message.substring(0, 200)}`));
-        console.log(chalk.cyan(`\n  📄 Full details in log file`));
-        console.log('');
+                logger.info(`Found ${irisApps.length} Iris apps to download`);
+
+                for (let i = 0; i < irisApps.length; i++) {
+                    const app = irisApps[i];
+                    progress.updateProgress('download-iris', i + 1, irisApps.length, `Downloading ${app.folderName}...`);
+
+                    try {
+                        // Download the app as a buffer
+                        const { buffer } = await downloadApp(instanceUrl, token.value, app.folderName);
+
+                        // Extract to iris-apps directory
+                        const appDir = path.join(irisAppsDir, app.folderName);
+
+                        // Remove existing app directory if it exists
+                        if (fs.existsSync(appDir)) {
+                            fs.rmSync(appDir, { recursive: true, force: true });
+                        }
+
+                        // Extract the zip (it contains a folder with the app name)
+                        await extractIrisZip(buffer, irisAppsDir);
+
+                        // Calculate content hash for change detection
+                        const contentHash = hashIrisAppFolder(appDir);
+
+                        // Update base.json for this Iris app
+                        updateBase(appDir, {
+                            Id: `iris-app:${app.folderName}`,
+                            Type: 'IrisApp',
+                            folderName: app.folderName,
+                            uploadedOn: app.uploadedOn,
+                            modifiedOn: app.modifiedOn,
+                            size: app.size,
+                            contentHash  // Store hash for change detection
+                        }, appDir);
+
+                        logger.info(`Downloaded Iris app: ${app.folderName}`);
+                    } catch (appError) {
+                        // Detect permission errors and provide helpful hint
+                        const isPermissionError = appError.code === 'EACCES' || appError.code === 'EPERM' ||
+                            appError.message?.includes('permission denied') || appError.message?.includes('EACCES');
+
+                        // Create a more informative error message
+                        const errorDetail = appError.message || String(appError);
+                        const errorMsg = `Failed to download Iris app ${app.folderName}: ${errorDetail}`;
+
+                        if (isPermissionError) {
+                            const hint = `Try: sudo chown -R $(whoami):staff "${irisAppsDir}"`;
+                            logger.error(errorMsg, appError, null, hint);
+                            irisDownloadErrors.push({ app: app.folderName, error: appError.message, isPermissionError: true, hint });
+                            progress.addIssue('error', errorMsg, hint);
+                        } else {
+                            logger.error(errorMsg, appError);
+                            irisDownloadErrors.push({ app: app.folderName, error: appError.message });
+                            progress.addIssue('error', errorMsg);
+                        }
+                    }
+                }
 
-        // Initialize empty data structure
-        if (!assets) assets = { tree: [] };
+                progress.completeStep('download-iris', `✓ Downloaded ${irisApps.length} Iris apps`);
+            } else {
+                progress.completeStep('download-iris', '✓ No Iris apps found');
+            }
+        } catch (error) {
+            logger.error('Error fetching Iris apps', error);
+            irisDownloadErrors.push({ stage: 'iris-list', error: error.message });
+            progress.completeStep('download-iris', '⚠ Iris apps skipped (API may not be available)');
+        }
 
-        // Restart progress for next step
-        progress.start();
-    }
+        // Check if we have any data to continue with
+        if (!activeClassResult?.Records?.length && !activePageResult?.Records?.length && !assets?.tree?.length) {
+            throw new Error('Download failed completely. No data available to continue.');
+        }
 
-    // Check if we have any data to continue with
-    if (!activeClassResult?.Records?.length && !activePageResult?.Records?.length && !assets?.tree?.length) {
-        throw new Error('Download failed completely. No data available to continue.');
-    }
+        // Step 5: Process files and detect changes
+        progress.startStep('process');
+        const { allRecords, issues, deletionLogs, processingErrors } = await (async () => {
+            let processedCount = 0;
+            const totalToProcess = cachedAssets.length + (activeClassResult.Records.length + activePageResult.Records.length);
+            const processingErrors = [];
+
+            // Collect all server asset paths
+            const serverAssetPaths = new Set();
+            const collectServerPaths = (records) => {
+                try {
+                    for (const record of records) {
+                        const fullPath = path.join(EXPORT_ROOT, record?.Path);
+                        serverAssetPaths.add(path.normalize(fullPath));
+
+                        if (record?.Type === 'Folder' && record?.Children?.length > 0) {
+                            collectServerPaths(record.Children);
+                        }
+                    }
+                } catch (err) {
+                    processingErrors.push({ stage: 'collect-paths', error: err.message });
+                    logger.error('Error collecting server paths', err);
+                }
+            };
+            collectServerPaths(assets.tree);
+            progress.updateProgress('process', ++processedCount, totalToProcess, 'Collecting server paths');
+
+            // Detect and delete assets that were on server before but are now gone
+            const assetsToDelete = [];
+            for (const cached of cachedAssets) {
+                const cachedPath = path.normalize(cached.lastKnownActualPath || cached.filePath || cached.lastKnownPath);
+
+                // If this asset was in base.json but not returned from server, it was deleted
+                if (!serverAssetPaths.has(cachedPath)) {
+                    assetsToDelete.push(cachedPath);
+                }
 
-    // Step 5: Process files and detect changes
-    progress.startStep('process');
-    const { allRecords, issues, deletionLogs, processingErrors } = await (async () => {
-        let processedCount = 0;
-        const totalToProcess = cachedAssets.length + (activeClassResult.Records.length + activePageResult.Records.length);
-        const processingErrors = [];
-
-        // Collect all server asset paths
-        const serverAssetPaths = new Set();
-        const collectServerPaths = (records) => {
-            try {
+                processedCount++;
+                if (processedCount % 50 === 0) {
+                    progress.updateProgress('process', processedCount, totalToProcess, `Checking assets...`);
+                }
+            }
+            progress.updateProgress('process', processedCount, totalToProcess, `Found ${assetsToDelete.length} assets to delete`);
+
+            // Count total assets (for progress tracking)
+            // Note: We don't update base.json for assets here because:
+            // 1. Assets are already downloaded and written to disk
+            // 2. Their base will be updated during the "Writing files" stage if modified
+            // 3. Updating base.json thousands of times here is extremely slow
+            logger.info('Counting assets in tree');
+            let assetCount = 0;
+            const countAssets = (records) => {
                 for (const record of records) {
-                    const fullPath = path.join(EXPORT_ROOT, record?.Path);
-                    serverAssetPaths.add(path.normalize(fullPath));
-
+                    assetCount++;
                     if (record?.Type === 'Folder' && record?.Children?.length > 0) {
-                        collectServerPaths(record.Children);
+                        countAssets(record.Children);
                     }
                 }
-            } catch (err) {
-                processingErrors.push({ stage: 'collect-paths', error: err.message });
-                logger.error('Error collecting server paths', err);
-            }
-        };
-        collectServerPaths(assets.tree);
-        progress.updateProgress('process', ++processedCount, totalToProcess, 'Collecting server paths');
-
-        // Detect and delete assets that were on server before but are now gone
-        const assetsToDelete = [];
-        for (const cached of cachedAssets) {
-            const cachedPath = path.normalize(cached.lastKnownActualPath || cached.filePath || cached.lastKnownPath);
-
-            // If this asset was in base.json but not returned from server, it was deleted
-            if (!serverAssetPaths.has(cachedPath)) {
-                assetsToDelete.push(cachedPath);
             }
 
-            processedCount++;
-            if (processedCount % 50 === 0) {
-                progress.updateProgress('process', processedCount, totalToProcess, `Checking assets...`);
+            countAssets(assets.tree);
+            logger.info(`Counted ${assetCount} total assets`);
+            processedCount += assetCount;
+            progress.updateProgress('process', processedCount, totalToProcess, `Processed ${assetCount} assets`);
+
+            // Handle code entity (ActiveClass, ActivePage) deletions
+            const activeClassRecords = (activeClassResult.Records || []).map(record => {
+                record.Content = record.Body;
+                delete record.Body;
+                return record;
+            });
+
+            const activePageRecords = (activePageResult.Records || []);
+            const allRecords = [...activeClassRecords, ...activePageRecords].map(mapRecordToFile);
+
+            // Get all server record IDs
+            const serverRecordIds = new Set([
+                ...activeClassRecords.map(r => r.Id),
+                ...activePageRecords.map(r => r.Id)
+            ]);
+
+            // Find code entities in base.json that are no longer on server
+            // Exclude Files, Folders, and IrisApps - only ActiveClass and ActivePage
+            const cachedCodeEntities = Object.values(cachedResults).filter(c =>
+                c.type !== 'File' && c.type !== 'Folder' && c.type !== 'IrisApp' && c.recordId
+            );
+
+            const codeEntitiesToDelete = [];
+            for (const cached of cachedCodeEntities) {
+                // If this code entity was in base.json but not returned from server, it was deleted
+                if (!serverRecordIds.has(cached.recordId)) {
+                    codeEntitiesToDelete.push(cached);
+                }
             }
-        }
-        progress.updateProgress('process', processedCount, totalToProcess, `Found ${assetsToDelete.length} assets to delete`);
-
-        // Count total assets (for progress tracking)
-        // Note: We don't update base.json for assets here because:
-        // 1. Assets are already downloaded and written to disk
-        // 2. Their base will be updated during the "Writing files" stage if modified
-        // 3. Updating base.json thousands of times here is extremely slow
-        logger.info('Counting assets in tree');
-        let assetCount = 0;
-        const countAssets = (records) => {
-            for (const record of records) {
-                assetCount++;
-                if (record?.Type === 'Folder' && record?.Children?.length > 0) {
-                    countAssets(record.Children);
+
+            // Delete local files/folders that were deleted on server
+            logger.info(`Starting deletion of ${assetsToDelete.length} assets`);
+            const deletionLogs = [];
+            for (const assetPath of assetsToDelete) {
+                try {
+                    if (fs.existsSync(assetPath)) {
+                        const stats = fs.statSync(assetPath);
+                        if (stats.isDirectory()) {
+                            fs.rmSync(assetPath, { recursive: true, force: true });
+                            deletionLogs.push({ type: 'folder', path: assetPath });
+                            logger.info('Deleted folder', { path: assetPath });
+                        } else {
+                            fs.unlinkSync(assetPath);
+                            deletionLogs.push({ type: 'file', path: assetPath });
+                            logger.info('Deleted file', { path: assetPath });
+                        }
+                    }
+                } catch (err) {
+                    deletionLogs.push({ type: 'error', path: assetPath, error: err.message });
+                    logger.error(`Failed to delete asset: ${assetPath}`, err);
                 }
             }
-        }
 
-        countAssets(assets.tree);
-        logger.info(`Counted ${assetCount} total assets`);
-        processedCount += assetCount;
-        progress.updateProgress('process', processedCount, totalToProcess, `Processed ${assetCount} assets`);
-
-        // Handle code entity (ActiveClass, ActivePage) deletions
-        const activeClassRecords = (activeClassResult.Records || []).map(record => {
-            record.Content = record.Body;
-            delete record.Body;
-            return record;
-        });
-
-        const activePageRecords = (activePageResult.Records || []);
-        const allRecords = [...activeClassRecords, ...activePageRecords].map(mapRecordToFile);
-
-        // Get all server record IDs
-        const serverRecordIds = new Set([
-            ...activeClassRecords.map(r => r.Id),
-            ...activePageRecords.map(r => r.Id)
-        ]);
-
-        // Find code entities in base.json that are no longer on server
-        const cachedCodeEntities = Object.values(cachedResults).filter(c =>
-            c.type !== 'File' && c.type !== 'Folder' && c.recordId
-        );
+            // Bulk remove from base.json
+            const assetPathsToRemove = deletionLogs
+                .filter(l => l.type === 'file' || l.type === 'folder')
+                .map(l => l.path);
 
-        const codeEntitiesToDelete = [];
-        for (const cached of cachedCodeEntities) {
-            // If this code entity was in base.json but not returned from server, it was deleted
-            if (!serverRecordIds.has(cached.recordId)) {
-                codeEntitiesToDelete.push(cached);
+            if (assetPathsToRemove.length > 0) {
+                removeFromBaseBulk(assetPathsToRemove);
             }
-        }
 
-        // Delete local files/folders that were deleted on server
-        logger.info(`Starting deletion of ${assetsToDelete.length} assets`);
-        const deletionLogs = [];
-        for (const assetPath of assetsToDelete) {
-            try {
-                if (fs.existsSync(assetPath)) {
-                    const stats = fs.statSync(assetPath);
-                    if (stats.isDirectory()) {
-                        fs.rmSync(assetPath, { recursive: true, force: true });
-                        deletionLogs.push({ type: 'folder', path: assetPath });
-                        logger.info('Deleted folder', { path: assetPath });
+            // Delete local code entity files that were deleted on server
+            logger.info(`Starting deletion of ${codeEntitiesToDelete.length} code entities`);
+            for (const entity of codeEntitiesToDelete) {
+                const entityPath = entity.filePath || entity.lastKnownPath;
+                try {
+                    if (entityPath && fs.existsSync(entityPath)) {
+                        fs.unlinkSync(entityPath);
+                        deletionLogs.push({ type: 'entity', path: entityPath, entityType: entity.type });
+                        logger.info('Deleted code entity', { path: entityPath, type: entity.type });
+                    }
+                } catch (err) {
+                    // Detect permission errors
+                    const isPermissionError = err.code === 'EACCES' || err.code === 'EPERM';
+                    deletionLogs.push({ type: 'error', path: entityPath, error: err.message, isPermissionError });
+
+                    if (isPermissionError) {
+                        const hint = `Try: sudo chown -R $(whoami):staff "${path.dirname(entityPath)}"`;
+                        logger.error(`Failed to delete code entity: ${entityPath}`, err, null, hint);
+                        progress.addIssue('error', `Failed to delete code entity: ${entityPath}`, hint);
                     } else {
-                        fs.unlinkSync(assetPath);
-                        deletionLogs.push({ type: 'file', path: assetPath });
-                        logger.info('Deleted file', { path: assetPath });
+                        logger.error(`Failed to delete code entity: ${entityPath}`, err);
+                        progress.addIssue('error', `Failed to delete code entity: ${entityPath}`);
                     }
                 }
-                // Remove from base.json
-                removeFromBase(assetPath);
-            } catch (err) {
-                deletionLogs.push({ type: 'error', path: assetPath, error: err.message });
-                logger.error(`Failed to delete asset: ${assetPath}`, err);
             }
-        }
 
-        // Delete local code entity files that were deleted on server
-        logger.info(`Starting deletion of ${codeEntitiesToDelete.length} code entities`);
-        for (const entity of codeEntitiesToDelete) {
-            const entityPath = entity.filePath || entity.lastKnownPath;
-            try {
-                if (entityPath && fs.existsSync(entityPath)) {
-                    fs.unlinkSync(entityPath);
-                    deletionLogs.push({ type: 'entity', path: entityPath, entityType: entity.type });
-                    logger.info('Deleted code entity', { path: entityPath, type: entity.type });
-                }
-                // Remove from base.json
-                removeFromBase(entity.recordId);
-            } catch (err) {
-                deletionLogs.push({ type: 'error', path: entityPath, error: err.message });
-                logger.error(`Failed to delete code entity: ${entityPath}`, err);
+            // Bulk remove code entities from base.json
+            const entityIdsToRemove = deletionLogs
+                .filter(l => l.type === 'entity')
+                .map(l => {
+                    // Find the entity object that corresponds to this path to get the ID
+                    const entity = codeEntitiesToDelete.find(e =>
+                        (e.filePath === l.path || e.lastKnownPath === l.path)
+                    );
+                    return entity ? entity.recordId : null;
+                })
+                .filter(id => id !== null);
+
+            if (entityIdsToRemove.length > 0) {
+                removeFromBaseBulk(entityIdsToRemove);
             }
-        }
-        logger.info(`Completed deletions - ${deletionLogs.length} items deleted`);
-        progress.updateProgress('process', processedCount, totalToProcess, `Deleted ${deletionLogs.length} items`);
-
-        // Compare files and detect conflicts
-        logger.info(`Starting file comparison for ${allRecords.length} records`);
-        const issues = [];
-        for (let i = 0; i < allRecords.length; i++) {
-            const record = allRecords[i];
-            try {
-                if (record?.error) {
-                    logger.warning('Record has error', { record: record.Name || record.relativePath });
-                    processingErrors.push({
-                        stage: 'record-error',
-                        file: record.Name || record.relativePath,
-                        error: 'Record contains error flag'
-                    });
-                    continue;
+            logger.info(`Completed deletions - ${deletionLogs.length} items deleted`);
+            progress.updateProgress('process', processedCount, totalToProcess, `Deleted ${deletionLogs.length} items`);
+
+            // Compare files and detect conflicts
+            logger.info(`Starting file comparison for ${allRecords.length} records`);
+            // --- Fix for Bug 1: Rename Tracking ---
+            // Build a map of RecordId -> LocalPath from cached results
+            const localPathMap = new Map();
+            Object.values(cachedResults).forEach(entry => {
+                if (entry.recordId && (entry.filePath || entry.lastKnownPath)) {
+                    localPathMap.set(entry.recordId, entry.filePath || entry.lastKnownPath);
                 }
+            });
+
+            // Check for renames before comparison
+            for (const record of allRecords) {
+                if (localPathMap.has(record.Id)) {
+                    const oldPath = localPathMap.get(record.Id);
+                    const newPath = path.join(EXPORT_ROOT, record.relativePath);
+
+                    // Normalize paths for comparison
+                    let normalizedOld = path.normalize(path.resolve(oldPath));
+                    const normalizedNew = path.normalize(path.resolve(newPath));
+
+                    // Fix for path resolution: base.json might store paths relative to CWD or EXPORT_ROOT
+                    // If direct resolution fails, try prepending EXPORT_ROOT
+                    if (!fs.existsSync(normalizedOld)) {
+                        const withRoot = path.normalize(path.resolve(EXPORT_ROOT, oldPath));
+                        if (fs.existsSync(withRoot)) {
+                            normalizedOld = withRoot;
+                        }
+                    }
 
-                // Log every 50th file to track progress
-                if (i % 50 === 0) {
-                    logger.info(`Comparing file ${i + 1}/${allRecords.length}: ${record.relativePath}`);
+                    if (normalizedOld !== normalizedNew && fs.existsSync(normalizedOld)) {
+                        try {
+                            logger.info(`Detected rename: ${path.relative(EXPORT_ROOT, oldPath)} -> ${record.relativePath}`);
+
+                            // Ensure target directory exists
+                            fs.mkdirSync(path.dirname(normalizedNew), { recursive: true });
+
+                            // Rename file
+                            fs.renameSync(normalizedOld, normalizedNew);
+
+                            // Update fileIdIndex.json to point to the new path
+                            // This must be done BEFORE writeRecords runs, otherwise findFileByTag
+                            // will return the old path and writeRecords will recreate the old file
+                            await setFileTag(normalizedNew, record.Id);
+
+                            // Update base.json immediately to reflect new path
+                            // We use the existing record data but update the path
+                            updateBase(record.relativePath, record, normalizedNew);
+
+                            // Remove old path from deletion logs if it was marked for deletion
+                            // (It might have been marked if the old filename wasn't in the server response)
+                            const deletionIndex = deletionLogs.findIndex(l => path.normalize(l.path) === normalizedOld);
+                            if (deletionIndex !== -1) {
+                                deletionLogs.splice(deletionIndex, 1);
+                                logger.info(`Cancelled deletion of renamed file: ${path.relative(EXPORT_ROOT, oldPath)}`);
+                            }
+
+                            console.log(chalk.cyan(`  ↻ Renamed: ${path.relative(EXPORT_ROOT, oldPath)} -> ${record.relativePath}`));
+                        } catch (err) {
+                            logger.error(`Failed to rename file: ${oldPath} -> ${newPath}`, err);
+                            processingErrors.push({
+                                stage: 'rename',
+                                file: record.relativePath,
+                                error: `Rename failed: ${err.message}`
+                            });
+                        }
+                    }
                 }
+            }
+            // --- End Fix for Bug 1 ---
+
+            const issues = [];
+            for (let i = 0; i < allRecords.length; i++) {
+                const record = allRecords[i];
+                try {
+                    if (record?.error) {
+                        logger.warning('Record has error', { record: record.Name || record.relativePath });
+                        processingErrors.push({
+                            stage: 'record-error',
+                            file: record.Name || record.relativePath,
+                            error: 'Record contains error flag'
+                        });
+                        continue;
+                    }
+
+                    // Log every 50th file to track progress
+                    if (i % 50 === 0) {
+                        logger.info(`Comparing file ${i + 1}/${allRecords.length}: ${record.relativePath}`);
+                    }
 
-                const status = compareLocalAndRemote(
-                    path.join(EXPORT_ROOT, record.relativePath),
-                    { ...record, content: record.Content }
-                );
+                    const status = compareLocalAndRemote(
+                        path.join(EXPORT_ROOT, record.relativePath),
+                        { ...record, content: record.Content }
+                    );
 
-                // Missing files will just be written
-                if (!['in_sync', 'missing'].includes(status.status)) {
-                    issues.push({ relativePath: record.relativePath, status: status.status });
-                    logger.info('Conflict detected', { file: record.relativePath, status: status.status });
+                    // Missing files will just be written
+                    if (!['in_sync', 'missing'].includes(status.status)) {
+                        issues.push({ relativePath: record.relativePath, status: status.status });
+                        logger.info('Conflict detected', { file: record.relativePath, status: status.status });
+                    }
+                } catch (err) {
+                    processingErrors.push({
+                        stage: 'compare-files',
+                        file: record?.relativePath || record?.Name,
+                        error: err.message
+                    });
+                    logger.error(`Error comparing file ${record?.relativePath}`, err);
                 }
-            } catch (err) {
-                processingErrors.push({
-                    stage: 'compare-files',
-                    file: record?.relativePath || record?.Name,
-                    error: err.message
-                });
-                logger.error(`Error comparing file ${record?.relativePath}`, err);
-            }
 
-            processedCount++;
-            if (processedCount % 10 === 0 || i === allRecords.length - 1) {
-                progress.updateProgress('process', processedCount, totalToProcess, `Comparing files...`);
+                processedCount++;
+                if (processedCount % 10 === 0 || i === allRecords.length - 1) {
+                    progress.updateProgress('process', processedCount, totalToProcess, `Comparing files...`);
+                }
             }
-        }
-        logger.info(`Completed file comparison - found ${issues.length} conflicts`);
+            logger.info(`Completed file comparison - found ${issues.length} conflicts`);
 
-        return { allRecords, issues, deletionLogs, processingErrors };
-    })();
+            return { allRecords, issues, deletionLogs, processingErrors };
+        })();
 
-    // Show completion message with error count if any
-    if (processingErrors.length > 0) {
-        progress.completeStep('process', `⚠ Processed ${allRecords.length} records with ${processingErrors.length} errors`);
-    } else {
-        progress.completeStep('process', `✓ Processed ${allRecords.length} records, ${deletionLogs.length} deletions`);
-    }
+        // Show completion message with error count if any
+        if (processingErrors.length > 0) {
+            progress.completeStep('process', `⚠ Processed ${allRecords.length} records with ${processingErrors.length} errors`);
+        } else {
+            progress.completeStep('process', `✓ Processed ${allRecords.length} records, ${deletionLogs.length} deletions`);
+        }
+
+        // Note: Error preview will be shown in final summary, not here to avoid UI glitches
+        // Pause progress display for deletion logs and conflict resolution
+        progress.stopSpinner();
 
-    // Note: Error preview will be shown in final summary, not here to avoid UI glitches
-    // Pause progress display for deletion logs and conflict resolution
-    progress.stopSpinner();
-
-    // Display deletion logs
-    for (const log of deletionLogs) {
-        if (log.type === 'folder') {
-            console.log(chalk.gray(`  🗑️  Removed deleted folder: ${path.relative(process.cwd(), log.path)}`));
-        } else if (log.type === 'file') {
-            console.log(chalk.gray(`  🗑️  Removed deleted file: ${path.relative(process.cwd(), log.path)}`));
-        } else if (log.type === 'entity') {
-            console.log(chalk.gray(`  🗑️  Removed deleted ${log.entityType}: ${path.relative(process.cwd(), log.path)}`));
-        } else if (log.type === 'error') {
-            console.warn(chalk.yellow(`  ⚠️  Could not delete ${log.path}: ${log.error}`));
+        // Display deletion logs
+        for (const log of deletionLogs) {
+            if (log.type === 'folder') {
+                console.log(chalk.gray(`  🗑️  Removed deleted folder: ${path.relative(process.cwd(), log.path)}`));
+            } else if (log.type === 'file') {
+                console.log(chalk.gray(`  🗑️  Removed deleted file: ${path.relative(process.cwd(), log.path)}`));
+            } else if (log.type === 'entity') {
+                console.log(chalk.gray(`  🗑️  Removed deleted ${log.entityType}: ${path.relative(process.cwd(), log.path)}`));
+            } else if (log.type === 'error') {
+                console.warn(chalk.yellow(`  ⚠️  Could not delete ${log.path}: ${log.error}`));
+            }
         }
-    }
 
-    let resolutionMethod = 'skip';
+        let resolutionMethod = 'skip';
 
-    // Check for conflicts
-    progress.startStep('conflicts');
-    if (issues.length > 0) {
-        progress.stopSpinner();
-        resolutionMethod = await promptConflictResolution(issues);
-        progress.startSpinner();
-    }
-    progress.completeStep('conflicts', issues.length > 0 ? `✓ Resolved ${issues.length} conflicts` : '✓ No conflicts');
+        // Check for conflicts
+        progress.startStep('conflicts');
+        if (issues.length > 0) {
+            progress.stopSpinner();
+            resolutionMethod = await promptConflictResolution(issues);
+            progress.startSpinner();
+        }
+        progress.completeStep('conflicts', issues.length > 0 ? `✓ Resolved ${issues.length} conflicts` : '✓ No conflicts');
 
-    // Step 6: Write all ActiveClass and ActivePage records
-    progress.startStep('write');
-    await writeRecords(allRecords, resolutionMethod, progress, logger);
-    progress.completeStep('write', `✓ Wrote ${allRecords.length} files`);
+        // Step 6: Write all ActiveClass and ActivePage records
+        progress.startStep('write');
+        await writeRecords(allRecords, resolutionMethod, progress, logger);
+        progress.completeStep('write', `✓ Wrote ${allRecords.length} files`);
 
         // Step 7: Finish progress tracker
         logger.info('Pull completed successfully');
@@ -456,6 +646,9 @@ export const pull = async () => {
         console.log(chalk.bold(`Summary:`));
         console.log(`   • ${activeClassResult.Records.length} ActiveClass records`);
         console.log(`   • ${activePageResult.Records.length} ActivePage records`);
+        if (irisApps.length > 0) {
+            console.log(`   • ${irisApps.length} Iris apps`);
+        }
         console.log(`   • ${deletionLogs.length} deletions`);
         console.log(`📁 Saved to: ./${EXPORT_ROOT}/`);