@magentrix-corp/magentrix-cli 1.3.16 → 1.3.17

package/actions/pull.js

@@ -1,684 +1,684 @@
-import { ensureValidCredentials } from "../utils/cli/helpers/ensureCredentials.js";
-import debug from '../utils/debug.js';
-import Config from "../utils/config.js";
-import { meqlQuery } from "../utils/magentrix/api/meqlQuery.js";
-import fs from "fs";
-import { ProgressTracker } from "../utils/progress.js";
-import { createLogger, Logger } from "../utils/logger.js";
-import { EXPORT_ROOT, IRIS_APPS_DIR } from "../vars/global.js";
-import { mapRecordToFile, writeRecords } from "../utils/cli/writeRecords.js";
-import { updateBase, removeFromBaseBulk } from "../utils/updateFileBase.js";
-import { promptConflictResolution } from "../utils/cli/helpers/compare.js";
-import path from "path";
-import { compareLocalAndRemote } from "../utils/compare.js";
-import chalk from 'chalk';
-import { setFileTag } from "../utils/filetag.js";
-import { downloadAssets } from "../utils/downloadAssets.js";
-import { listApps, downloadApp } from "../utils/magentrix/api/iris.js";
-import { extractIrisZip, hashIrisAppFolder } from "../utils/iris/zipper.js";
-import readlineSync from 'readline-sync';
-
-const config = new Config();
-
-/**
- * Pulls all ActiveClass and ActivePage records from Magentrix, 
- * saving them to categorized local directories with appropriate extensions.
- *
- * Output Structure:
- *   /test/
- *     Controllers/
- *     Triggers/
- *     Classes/
- *     Pages/
- *       <Name>.<ext>
- *
- * @async
- * @function pull
- * @returns {Promise<void>}
- */
-export const pull = async () => {
-    // Clear the terminal
-    process.stdout.write('\x1Bc');
-
-    // Clean up old log files (keep last 10)
-    Logger.cleanupOldLogs(10);
-
-    // Create logger
-    const logger = createLogger('pull');
-    await logger.initLogFile(); // Initialize with user preference check
-    logger.info('Starting pull operation');
-
-    // Create progress tracker
-    const progress = new ProgressTracker('Pull from Magentrix');
-    progress.addStep('auth', 'Authenticating...');
-    progress.addStep('check', 'Checking instance...');
-    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 });
-    progress.start();
-
-    try {
-        // Step 1: Authenticate and retrieve instance URL and token
-        progress.startStep('auth');
-        debug.log('PULL', 'Step 1: Authenticating...');
-        const { instanceUrl, token } = await ensureValidCredentials();
-        debug.log('PULL', `Authenticated with instance: ${instanceUrl}`);
-        progress.completeStep('auth', '✓ Authenticated');
-
-        // Step 2: Check if instance URL has changed (credential switch detected)
-        progress.startStep('check');
-        const lastInstanceUrl = config.read('lastInstanceUrl', { global: false, filename: 'config.json' });
-        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: `)
-            );
-
-            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');
-        }
-
-        // 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 || {};
-        // Include the base.json key (_baseKey) alongside each entry so we can
-        // use the correct key for removeFromBaseBulk later. The keys may differ
-        // from lastKnownActualPath/filePath due to path format inconsistencies.
-        const cachedAssets = Object.entries(cachedResults)
-            .filter(([, c]) => c.type === 'File' || c.type === 'Folder')
-            .map(([key, c]) => ({ ...c, _baseKey: key }));
-        progress.completeStep('load', `✓ Loaded ${Object.keys(cachedResults).length} cached entries`);
-
-        // Step 4a: Download code entities (ActiveClass and ActivePage)
-        progress.startStep('download-code');
-        debug.log('PULL', 'Step 4a: Downloading code entities...');
-        debug.log('PULL', `Queries: ${queries.map(q => q.query).join(' | ')}`);
-
-        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');
-        }
-
-        // Step 4b: Download static assets
-        if (!codeDownloadErrors.length) {
-            progress.startStep('download-assets');
-        }
-
-        let assets;
-        const assetDownloadErrors = [];
-
-        debug.log('PULL', 'Step 4b: Downloading static assets...');
-        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 4c: Download Iris apps
-        progress.startStep('download-iris');
-        let irisApps = [];
-        const irisDownloadErrors = [];
-
-        try {
-            logger.info('Fetching Iris apps list');
-            const irisListResult = await listApps(instanceUrl, token.value);
-
-            if (irisListResult.success && irisListResult.apps && irisListResult.apps.length > 0) {
-                irisApps = irisListResult.apps;
-                const irisAppsDir = path.resolve(EXPORT_ROOT, IRIS_APPS_DIR);
-
-                // Ensure iris-apps directory exists
-                if (!fs.existsSync(irisAppsDir)) {
-                    fs.mkdirSync(irisAppsDir, { recursive: true });
-                }
-
-                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);
-                        }
-                    }
-                }
-
-                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)');
-        }
-
-        // 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({ path: cachedPath, baseKey: cached._baseKey });
-                }
-
-                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) {
-                    assetCount++;
-                    if (record?.Type === 'Folder' && record?.Children?.length > 0) {
-                        countAssets(record.Children);
-                    }
-                }
-            }
-
-            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);
-                }
-            }
-
-            // Delete local files/folders that were deleted on server
-            logger.info(`Starting deletion of ${assetsToDelete.length} assets`);
-            const deletionLogs = [];
-            // Track base.json keys for entries that need removal
-            const assetBaseKeysToRemove = [];
-            for (const asset of assetsToDelete) {
-                try {
-                    if (fs.existsSync(asset.path)) {
-                        const stats = fs.statSync(asset.path);
-                        if (stats.isDirectory()) {
-                            fs.rmSync(asset.path, { recursive: true, force: true });
-                            deletionLogs.push({ type: 'folder', path: asset.path });
-                            logger.info('Deleted folder', { path: asset.path });
-                        } else {
-                            fs.unlinkSync(asset.path);
-                            deletionLogs.push({ type: 'file', path: asset.path });
-                            logger.info('Deleted file', { path: asset.path });
-                        }
-                    }
-                    // Always remove from base.json regardless of whether the local file
-                    // existed — the server confirmed deletion, so the cache entry is stale.
-                    assetBaseKeysToRemove.push(asset.baseKey);
-                } catch (err) {
-                    deletionLogs.push({ type: 'error', path: asset.path, error: err.message });
-                    logger.error(`Failed to delete asset: ${asset.path}`, err);
-                }
-            }
-
-            // Bulk remove from base.json using the original base.json keys
-            // (not the normalized paths, which may have a different format)
-            if (assetBaseKeysToRemove.length > 0) {
-                removeFromBaseBulk(assetBaseKeysToRemove);
-            }
-
-            // 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 {
-                        logger.error(`Failed to delete code entity: ${entityPath}`, err);
-                        progress.addIssue('error', `Failed to delete code entity: ${entityPath}`);
-                    }
-                }
-            }
-
-            // 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`);
-            // --- 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;
-                        }
-                    }
-
-                    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 }
-                    );
-
-                    // 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);
-                }
-
-                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`);
-
-            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`);
-        }
-
-        // 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}`));
-            }
-        }
-
-        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');
-
-        // 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');
-        logger.close();
-        debug.log('PULL', 'Pull completed successfully');
-        debug.close();
-        progress.finish('Pull completed successfully!');
-
-        // Clear any incomplete-pull marker (set by vue-run-build when a pull is
-        // started but cancelled/fails). A successful pull means we're fully synced.
-        config.removeKey('pullIncomplete', { filename: 'config.json' });
-
-        // Summary
-        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}/`);
-
-        // Display log summary
-        logger.displaySummary();
-    } catch (error) {
-        logger.error('Pull operation failed', error);
-        logger.close();
-        debug.log('PULL', `Pull failed: ${error.message}`, error.stack);
-        debug.close();
-        progress.abort(error.message);
-
-        // Display log summary even on failure
-        logger.displaySummary();
-
-        console.error(chalk.red('\nPull failed. Please check the error above and the log file for details.'));
-        throw error;
-    }
-};
+import { ensureValidCredentials } from "../utils/cli/helpers/ensureCredentials.js";
+import debug from '../utils/debug.js';
+import Config from "../utils/config.js";
+import { meqlQuery } from "../utils/magentrix/api/meqlQuery.js";
+import fs from "fs";
+import { ProgressTracker } from "../utils/progress.js";
+import { createLogger, Logger } from "../utils/logger.js";
+import { EXPORT_ROOT, IRIS_APPS_DIR } from "../vars/global.js";
+import { mapRecordToFile, writeRecords } from "../utils/cli/writeRecords.js";
+import { updateBase, removeFromBaseBulk } from "../utils/updateFileBase.js";
+import { promptConflictResolution } from "../utils/cli/helpers/compare.js";
+import path from "path";
+import { compareLocalAndRemote } from "../utils/compare.js";
+import chalk from 'chalk';
+import { setFileTag } from "../utils/filetag.js";
+import { downloadAssets } from "../utils/downloadAssets.js";
+import { listApps, downloadApp } from "../utils/magentrix/api/iris.js";
+import { extractIrisZip, hashIrisAppFolder } from "../utils/iris/zipper.js";
+import readlineSync from 'readline-sync';
+
+const config = new Config();
+
+/**
+ * Pulls all ActiveClass and ActivePage records from Magentrix, 
+ * saving them to categorized local directories with appropriate extensions.
+ *
+ * Output Structure:
+ *   /test/
+ *     Controllers/
+ *     Triggers/
+ *     Classes/
+ *     Pages/
+ *       <Name>.<ext>
+ *
+ * @async
+ * @function pull
+ * @returns {Promise<void>}
+ */
+export const pull = async () => {
+    // Clear the terminal
+    process.stdout.write('\x1Bc');
+
+    // Clean up old log files (keep last 10)
+    Logger.cleanupOldLogs(10);
+
+    // Create logger
+    const logger = createLogger('pull');
+    await logger.initLogFile(); // Initialize with user preference check
+    logger.info('Starting pull operation');
+
+    // Create progress tracker
+    const progress = new ProgressTracker('Pull from Magentrix');
+    progress.addStep('auth', 'Authenticating...');
+    progress.addStep('check', 'Checking instance...');
+    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 });
+    progress.start();
+
+    try {
+        // Step 1: Authenticate and retrieve instance URL and token
+        progress.startStep('auth');
+        debug.log('PULL', 'Step 1: Authenticating...');
+        const { instanceUrl, token } = await ensureValidCredentials();
+        debug.log('PULL', `Authenticated with instance: ${instanceUrl}`);
+        progress.completeStep('auth', '✓ Authenticated');
+
+        // Step 2: Check if instance URL has changed (credential switch detected)
+        progress.startStep('check');
+        const lastInstanceUrl = config.read('lastInstanceUrl', { global: false, filename: 'config.json' });
+        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: `)
+            );
+
+            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');
+        }
+
+        // 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 || {};
+        // Include the base.json key (_baseKey) alongside each entry so we can
+        // use the correct key for removeFromBaseBulk later. The keys may differ
+        // from lastKnownActualPath/filePath due to path format inconsistencies.
+        const cachedAssets = Object.entries(cachedResults)
+            .filter(([, c]) => c.type === 'File' || c.type === 'Folder')
+            .map(([key, c]) => ({ ...c, _baseKey: key }));
+        progress.completeStep('load', `✓ Loaded ${Object.keys(cachedResults).length} cached entries`);
+
+        // Step 4a: Download code entities (ActiveClass and ActivePage)
+        progress.startStep('download-code');
+        debug.log('PULL', 'Step 4a: Downloading code entities...');
+        debug.log('PULL', `Queries: ${queries.map(q => q.query).join(' | ')}`);
+
+        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');
+        }
+
+        // Step 4b: Download static assets
+        if (!codeDownloadErrors.length) {
+            progress.startStep('download-assets');
+        }
+
+        let assets;
+        const assetDownloadErrors = [];
+
+        debug.log('PULL', 'Step 4b: Downloading static assets...');
+        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 4c: Download Iris apps
+        progress.startStep('download-iris');
+        let irisApps = [];
+        const irisDownloadErrors = [];
+
+        try {
+            logger.info('Fetching Iris apps list');
+            const irisListResult = await listApps(instanceUrl, token.value);
+
+            if (irisListResult.success && irisListResult.apps && irisListResult.apps.length > 0) {
+                irisApps = irisListResult.apps;
+                const irisAppsDir = path.resolve(EXPORT_ROOT, IRIS_APPS_DIR);
+
+                // Ensure iris-apps directory exists
+                if (!fs.existsSync(irisAppsDir)) {
+                    fs.mkdirSync(irisAppsDir, { recursive: true });
+                }
+
+                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);
+                        }
+                    }
+                }
+
+                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)');
+        }
+
+        // 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({ path: cachedPath, baseKey: cached._baseKey });
+                }
+
+                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) {
+                    assetCount++;
+                    if (record?.Type === 'Folder' && record?.Children?.length > 0) {
+                        countAssets(record.Children);
+                    }
+                }
+            }
+
+            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);
+                }
+            }
+
+            // Delete local files/folders that were deleted on server
+            logger.info(`Starting deletion of ${assetsToDelete.length} assets`);
+            const deletionLogs = [];
+            // Track base.json keys for entries that need removal
+            const assetBaseKeysToRemove = [];
+            for (const asset of assetsToDelete) {
+                try {
+                    if (fs.existsSync(asset.path)) {
+                        const stats = fs.statSync(asset.path);
+                        if (stats.isDirectory()) {
+                            fs.rmSync(asset.path, { recursive: true, force: true });
+                            deletionLogs.push({ type: 'folder', path: asset.path });
+                            logger.info('Deleted folder', { path: asset.path });
+                        } else {
+                            fs.unlinkSync(asset.path);
+                            deletionLogs.push({ type: 'file', path: asset.path });
+                            logger.info('Deleted file', { path: asset.path });
+                        }
+                    }
+                    // Always remove from base.json regardless of whether the local file
+                    // existed — the server confirmed deletion, so the cache entry is stale.
+                    assetBaseKeysToRemove.push(asset.baseKey);
+                } catch (err) {
+                    deletionLogs.push({ type: 'error', path: asset.path, error: err.message });
+                    logger.error(`Failed to delete asset: ${asset.path}`, err);
+                }
+            }
+
+            // Bulk remove from base.json using the original base.json keys
+            // (not the normalized paths, which may have a different format)
+            if (assetBaseKeysToRemove.length > 0) {
+                removeFromBaseBulk(assetBaseKeysToRemove);
+            }
+
+            // 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 {
+                        logger.error(`Failed to delete code entity: ${entityPath}`, err);
+                        progress.addIssue('error', `Failed to delete code entity: ${entityPath}`);
+                    }
+                }
+            }
+
+            // 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`);
+            // --- 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;
+                        }
+                    }
+
+                    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 }
+                    );
+
+                    // 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);
+                }
+
+                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`);
+
+            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`);
+        }
+
+        // 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}`));
+            }
+        }
+
+        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');
+
+        // 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');
+        logger.close();
+        debug.log('PULL', 'Pull completed successfully');
+        debug.close();
+        progress.finish('Pull completed successfully!');
+
+        // Clear any incomplete-pull marker (set by vue-run-build when a pull is
+        // started but cancelled/fails). A successful pull means we're fully synced.
+        config.removeKey('pullIncomplete', { filename: 'config.json' });
+
+        // Summary
+        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}/`);
+
+        // Display log summary
+        logger.displaySummary();
+    } catch (error) {
+        logger.error('Pull operation failed', error);
+        logger.close();
+        debug.log('PULL', `Pull failed: ${error.message}`, error.stack);
+        debug.close();
+        progress.abort(error.message);
+
+        // Display log summary even on failure
+        logger.displaySummary();
+
+        console.error(chalk.red('\nPull failed. Please check the error above and the log file for details.'));
+        throw error;
+    }
+};