@magentrix-corp/magentrix-cli 1.3.15 → 1.3.17

package/actions/publish.js

@@ -1,1420 +1,1420 @@
-import { walkFiles } from "../utils/cacher.js";
-import { ensureValidCredentials } from "../utils/cli/helpers/ensureCredentials.js";
-import Config from "../utils/config.js";
-import { withSpinner } from "../utils/spinner.js";
-import { ProgressTracker } from "../utils/progress.js";
-import fs from "fs";
-import path from "path";
-import chalk from "chalk";
-import {
-    ENTITY_FIELD_MAP,
-    ENTITY_TYPE_MAP,
-    EXPORT_ROOT,
-    TYPE_DIR_MAP,
-    IRIS_APPS_DIR,
-    ALLOWED_SRC_DIRS,
-} from "../vars/global.js";
-import { getFileTag, setFileTag } from "../utils/filetag.js";
-import { sha256 } from "../utils/hash.js";
-import { createEntity } from "../utils/magentrix/api/createEntity.js";
-import { updateEntity } from "../utils/magentrix/api/updateEntity.js";
-import { deleteEntity } from "../utils/magentrix/api/deleteEntity.js";
-import { removeFromBase, updateBase } from "../utils/updateFileBase.js";
-import { deleteAsset, uploadAsset, createFolder } from "../utils/magentrix/api/assets.js";
-import { toApiPath, toApiFolderPath } from "../utils/assetPaths.js";
-import { publishApp } from "../utils/magentrix/api/iris.js";
-import { createIrisZip, hashIrisAppFolder } from "../utils/iris/zipper.js";
-import { validateIrisAppFolder } from "../utils/iris/validator.js";
-import { getLinkedProjects } from "../utils/iris/linker.js";
-import { deleteIrisAppFromServer } from "../utils/iris/deleteHelper.js";
-
-const config = new Config();
-
-/* ==================== CONFIGURATION ==================== */
-
-/**
- * Set to true to process all operations sequentially (one at a time).
- * Set to false to process operations in parallel with intelligent grouping.
- *
- * Sequential mode is slower but avoids any potential race conditions or
- * server-side rate limiting issues.
- */
-const USE_SEQUENTIAL_PROCESSING = true;
-
-/* ==================== UTILITY FUNCTIONS ==================== */
-
-/**
- * Infers Magentrix entity metadata from a file path by walking up the directory tree.
- * @param {string} filePath - The file path to analyze
- * @returns {Object} { type, entity, contentField } for Magentrix API
- */
-const inferMeta = (filePath) => {
-    let currentPath = path.dirname(filePath);
-    const exportRootAbs = path.resolve(EXPORT_ROOT);
-
-    while (currentPath.startsWith(exportRootAbs)) {
-        const folderName = path.basename(currentPath);
-        const type = Object.keys(TYPE_DIR_MAP).find(
-            (k) => TYPE_DIR_MAP[k].directory === folderName
-        );
-
-        if (type) {
-            return {
-                type,
-                entity: ENTITY_TYPE_MAP[type],
-                contentField: ENTITY_FIELD_MAP[type],
-            };
-        }
-
-        const parentPath = path.dirname(currentPath);
-        if (parentPath === currentPath) break; // Reached root
-        currentPath = parentPath;
-    }
-
-    return { type: undefined, entity: undefined, contentField: undefined };
-};
-
-/**
- * Safely reads file content and computes hash.
- * @param {string} filePath - Path to the file
- * @returns {Object|null} { content, hash } or null on error
- */
-const readFileSafe = (filePath) => {
-    try {
-        const content = fs.readFileSync(filePath, "utf-8");
-        return { content, hash: sha256(content) };
-    } catch (err) {
-        console.error(chalk.red.bold("Error:") + " Unable to read file " + chalk.white.bold(filePath));
-        console.error(chalk.gray("→ Please verify the file exists and you have read permissions."));
-        return null;
-    }
-};
-
-/**
- * Formats multiline error messages with proper indentation.
- */
-const formatMultilineError = (err) => {
-    const lines = String(err).split(/\r?\n/);
-    return lines
-        .map((line, i) => {
-            const prefix = i === 0 ? `${chalk.redBright('  •')} ` : '    ';
-            return prefix + chalk.whiteBright(line);
-        })
-        .join('\n');
-};
-
-/**
- * Recursively walks a directory and returns all subdirectory paths.
- */
-const walkFolders = (dir) => {
-    if (!fs.existsSync(dir)) return [];
-
-    const folders = [];
-    const items = fs.readdirSync(dir, { withFileTypes: true });
-
-    for (const item of items) {
-        if (item.isDirectory()) {
-            const fullPath = path.join(dir, item.name);
-            folders.push(fullPath);
-            folders.push(...walkFolders(fullPath));
-        }
-    }
-
-    return folders;
-};
-
-/**
- * Gets display name for an action in log messages.
- */
-const getActionDisplayName = (action) => {
-    // Iris app actions
-    if (action.slug) return `${action.appName || action.slug} (${action.slug})`;
-    if (action.folderName) return action.folderName;
-    if (action.names) return action.names.join(", ");
-    if (action.type) return action.type;
-    if (action.filePath) return path.basename(action.filePath);
-    return '';
-};
-
-/* ==================== ACTION HANDLERS ==================== */
-
-/**
- * Handles CREATE action for code entities (ActiveClass/ActivePage).
- */
-const handleCreateAction = async (instanceUrl, apiKey, action) => {
-    const data = {
-        Name: path.basename(action.filePath, path.extname(action.filePath)),
-        Type: action.type,
-        ...action.fields
-    };
-
-    const result = await createEntity(instanceUrl, apiKey, action.entity, data);
-    return { recordId: result.recordId || result.id };
-};
-
-/**
- * Handles UPDATE action for code entities (ActiveClass/ActivePage).
- */
-const handleUpdateAction = async (instanceUrl, apiKey, action) => {
-    const data = { ...action.fields };
-
-    if (action.renamed) {
-        data.Name = path.basename(action.filePath, path.extname(action.filePath));
-    }
-
-    await updateEntity(instanceUrl, apiKey, action.entity, action.recordId, data);
-    return { recordId: action.recordId };
-};
-
-/**
- * Handles DELETE action for code entities (ActiveClass/ActivePage).
- */
-const handleDeleteAction = async (instanceUrl, apiKey, action) => {
-    return await deleteEntity(instanceUrl, apiKey, action.entity, action.recordId);
-};
-
-/**
- * Handles CREATE_STATIC_ASSET action.
- */
-const handleCreateStaticAssetAction = async (instanceUrl, apiKey, action) => {
-    const response = await uploadAsset(instanceUrl, apiKey, `/${action.folder}`, [action.filePath]);
-    if (response?.error) throw new Error(response.error);
-    return response;
-};
-
-/**
- * Handles DELETE_STATIC_ASSET action.
- */
-const handleDeleteStaticAssetAction = async (instanceUrl, apiKey, action) => {
-    try {
-        const response = await deleteAsset(instanceUrl, apiKey, `/${action.folder}`, action.names);
-        return response;
-    } catch (error) {
-        // Check if this is a "not found" error
-        const errorMessage = error?.message || String(error);
-        const errorLower = errorMessage.toLowerCase();
-        const isNotFound = errorLower.includes('404') ||
-            errorLower.includes('not found') ||
-            errorLower.includes('item not found');
-
-        if (isNotFound) {
-            // Clean up base.json since file doesn't exist on server
-            // Use the original base.json key if available (avoids path format mismatches)
-            if (action.baseKey) {
-                removeFromBase(action.baseKey);
-            } else {
-                for (const name of action.names) {
-                    const filePath = action.filePath || `${EXPORT_ROOT}/${action.folder}/${name}`;
-                    removeFromBase(filePath);
-                }
-            }
-            return { cleanedFromCache: true };
-        }
-
-        // Other errors should still fail
-        throw error;
-    }
-};
-
-/**
- * Handles CREATE_FOLDER action.
- */
-const handleCreateFolderAction = async (instanceUrl, apiKey, action) => {
-    try {
-        const response = await createFolder(instanceUrl, apiKey, action.parentPath, action.folderName);
-        return response;
-    } catch (error) {
-        // Check if folder already exists (likely created by file upload)
-        const errorMessage = error?.message || String(error);
-        const errorLower = errorMessage.toLowerCase();
-        const alreadyExists = errorLower.includes('already exists') ||
-            errorLower.includes('folder exists') ||
-            errorLower.includes('duplicate');
-
-        if (alreadyExists) {
-            // Folder already exists, update cache and treat as success
-            return { alreadyExisted: true };
-        }
-
-        // Other errors should still fail
-        throw error;
-    }
-};
-
-/**
- * Handles DELETE_FOLDER action.
- */
-const handleDeleteFolderAction = async (instanceUrl, apiKey, action) => {
-    try {
-        const response = await deleteAsset(instanceUrl, apiKey, action.parentPath, [action.folderName]);
-        return response;
-    } catch (error) {
-        // Check if this is a "not found" error
-        const errorMessage = error?.message || String(error);
-        const errorLower = errorMessage.toLowerCase();
-        const isNotFound = errorLower.includes('404') ||
-            errorLower.includes('not found') ||
-            errorLower.includes('item not found');
-
-        if (isNotFound) {
-            // Clean up base.json since folder doesn't exist on server
-            // Use original base.json key if available (avoids path format mismatches)
-            removeFromBase(action.baseKey || action.folderPath);
-
-            // Also remove all files and subfolders inside this folder from base
-            const hits = await config.searchObject({}, { filename: "base.json", global: false });
-            const cachedResults = hits?.[0]?.value || {};
-
-            for (const [recordId, cachedEntry] of Object.entries(cachedResults)) {
-                // Check all possible path fields
-                const entryPath = cachedEntry.lastKnownActualPath || cachedEntry.filePath || cachedEntry.lastKnownPath;
-                if (entryPath && typeof entryPath === 'string') {
-                    const normalizedEntryPath = path.normalize(path.resolve(entryPath)).toLowerCase();
-                    const normalizedFolderPath = path.normalize(path.resolve(action.folderPath)).toLowerCase();
-
-                    // Check if this entry is inside the deleted folder
-                    if (normalizedEntryPath.startsWith(normalizedFolderPath + path.sep) ||
-                        normalizedEntryPath === normalizedFolderPath) {
-                        removeFromBase(recordId);
-                    }
-                }
-            }
-
-            return { cleanedFromCache: true };
-        }
-
-        // Other errors should still fail
-        throw error;
-    }
-};
-
-/**
- * Handles CREATE_IRIS_APP or UPDATE_IRIS_APP action.
- */
-const handlePublishIrisAppAction = async (instanceUrl, apiKey, action) => {
-    // Create zip from the app folder
-    const zipBuffer = await createIrisZip(action.appPath, action.slug);
-
-    // For updates, don't send app-name/description/icon to avoid triggering
-    // metadata modification that may require permissions the user doesn't have.
-    // The server already has the correct metadata from the original create.
-    // For creates, send all metadata so the app is properly registered.
-    const isUpdate = action.action === 'update_iris_app';
-
-    const response = await publishApp(
-        instanceUrl,
-        apiKey,
-        zipBuffer,
-        `${action.slug}.zip`,
-        isUpdate ? null : action.appName,
-        isUpdate ? {} : {
-            appDescription: action.appDescription,
-            appIconId: action.appIconId
-        }
-    );
-
-    return response;
-};
-
-/**
- * Handles DELETE_IRIS_APP action.
- */
-const handleDeleteIrisAppAction = async (instanceUrl, apiKey, action) => {
-    // Use shared delete utility for consistency
-    return await deleteIrisAppFromServer(instanceUrl, apiKey, action.slug, {
-        updateCache: true  // Cache will be updated by the utility
-    });
-};
-
-/**
- * Synchronizes class name in content with filename, or vice versa.
- */
-const syncClassAndFileNames = (action, recordId) => {
-    // Only for ActiveClass
-    if (action.entity !== 'ActiveClass') return;
-
-    const filePath = action.filePath;
-    // If file was deleted or doesn't exist, skip
-    if (!fs.existsSync(filePath)) return;
-
-    const content = fs.readFileSync(filePath, 'utf-8');
-    const filename = path.basename(filePath, path.extname(filePath));
-
-    // Regex to find class/interface/enum name
-    // Matches: public class Name, public interface Name, public enum Name
-    // We assume standard formatting
-    const classRegex = /public\s+(?:class|interface|enum)\s+(\w+)/;
-    const match = content.match(classRegex);
-
-    if (match) {
-        const classNameInContent = match[1];
-
-        if (classNameInContent !== filename) {
-            // Mismatch detected
-
-            // Case 1: File was renamed (action.renamed is true) -> Update content
-            if (action.renamed) {
-                const newContent = content.replace(classRegex, (fullMatch, name) => {
-                    return fullMatch.replace(name, filename);
-                });
-                fs.writeFileSync(filePath, newContent);
-                console.log(chalk.cyan(`  ↻ Updated class name in file to: ${filename}`));
-
-                // Update cache with new content hash
-                updateBase(filePath, { Id: recordId, Type: 'ActiveClass' });
-            }
-            // Case 2: Content was updated (action.renamed is false) -> Rename file
-            else {
-                // Rename file to match class name
-                const dir = path.dirname(filePath);
-                const ext = path.extname(filePath);
-                const newFilename = `${classNameInContent}${ext}`;
-                const newFilePath = path.join(dir, newFilename);
-
-                if (fs.existsSync(newFilePath)) {
-                    console.warn(chalk.yellow(`  ⚠️  Cannot rename ${filename} to ${classNameInContent}: File already exists.`));
-                    return;
-                }
-
-                try {
-                    fs.renameSync(filePath, newFilePath);
-                    console.log(chalk.cyan(`  ↻ Renamed file to match class: ${newFilename}`));
-
-                    // Update cache: update the entry for this recordId to point to new path
-                    updateBase(newFilePath, { Id: recordId, Type: 'ActiveClass' }, newFilePath);
-                } catch (err) {
-                    console.warn(chalk.yellow(`  ⚠️  Failed to rename file: ${err.message}`));
-                }
-            }
-        }
-    }
-};
-
-/**
- * Updates cache after successful operations.
- */
-const updateCacheAfterSuccess = async (action, operationResult) => {
-    try {
-        // Sync class names/filenames if needed (Bug 2 Fix)
-        if (action.action === 'update' && operationResult?.recordId) {
-            syncClassAndFileNames(action, operationResult.recordId);
-        }
-
-        switch (action.action) {
-            case "create": {
-                const createSnapshot = action.fields && Object.values(action.fields)[0]
-                    ? { content: Object.values(action.fields)[0], hash: action.contentHash }
-                    : null;
-                await setFileTag(action.filePath, operationResult.recordId);
-                updateBase(
-                    action.filePath,
-                    { Id: operationResult.recordId, Type: action.type },
-                    '',
-                    createSnapshot
-                );
-                break;
-            }
-
-            case "update": {
-                const updateSnapshot = action.fields && Object.values(action.fields)[0]
-                    ? { content: Object.values(action.fields)[0], hash: sha256(Object.values(action.fields)[0]) }
-                    : null;
-                const type = Object.keys(ENTITY_TYPE_MAP).find(key => ENTITY_TYPE_MAP[key] === action.entity);
-                updateBase(
-                    action.filePath,
-                    { Id: action.recordId, Type: type },
-                    '',
-                    updateSnapshot
-                );
-                break;
-            }
-
-            case "delete":
-                removeFromBase(action.recordId);
-                break;
-
-            case "delete_static_asset":
-                // Skip if already cleaned from cache during 404 handling
-                if (!operationResult?.cleanedFromCache) {
-                    // Use the original base.json key if available (avoids path format mismatches)
-                    if (action.baseKey) {
-                        removeFromBase(action.baseKey);
-                    } else {
-                        for (const name of action.names) {
-                            const filePath = action.filePath || `${EXPORT_ROOT}/${action.folder}/${name}`;
-                            removeFromBase(filePath);
-                        }
-                    }
-                }
-                break;
-
-            case "create_static_asset":
-                updateBase(action.filePath, { Id: action.filePath, Type: "File" });
-                break;
-
-            case "create_folder":
-                updateBase(action.folderPath, { Id: action.folderPath, Type: "Folder" });
-                break;
-
-            case "delete_folder": {
-                // Skip if already cleaned from cache during 404 handling
-                if (!operationResult?.cleanedFromCache) {
-                    // Remove the folder itself from base using the original base.json key
-                    removeFromBase(action.baseKey || action.folderPath);
-
-                    // Also remove all files and subfolders inside this folder from base
-                    const hits = await config.searchObject({}, { filename: "base.json", global: false });
-                    const cachedResults = hits?.[0]?.value || {};
-
-                    for (const [recordId, cachedEntry] of Object.entries(cachedResults)) {
-                        // Check all possible path fields
-                        const entryPath = cachedEntry.lastKnownActualPath || cachedEntry.filePath || cachedEntry.lastKnownPath;
-                        if (entryPath && typeof entryPath === 'string') {
-                            const normalizedEntryPath = path.normalize(path.resolve(entryPath)).toLowerCase();
-                            const normalizedFolderPath = path.normalize(path.resolve(action.folderPath)).toLowerCase();
-
-                            // Check if this entry is inside the deleted folder
-                            if (normalizedEntryPath.startsWith(normalizedFolderPath + path.sep) ||
-                                normalizedEntryPath === normalizedFolderPath) {
-                                removeFromBase(recordId);
-                            }
-                        }
-                    }
-                }
-                break;
-            }
-
-            case "create_iris_app":
-            case "update_iris_app": {
-                // Update base.json with new/updated Iris app info including content hash
-                updateBase(action.appPath, {
-                    Id: `iris-app:${action.slug}`,
-                    Type: 'IrisApp',
-                    folderName: action.slug,
-                    appName: action.appName,
-                    modifiedOn: new Date().toISOString(),
-                    contentHash: action.contentHash  // Store hash for change detection
-                }, action.appPath);
-                break;
-            }
-
-            case "delete_iris_app": {
-                // Skip if already cleaned from cache during 404 handling
-                if (!operationResult?.cleanedFromCache) {
-                    removeFromBase(`iris-app:${action.slug}`);
-                }
-                break;
-            }
-        }
-    } catch (error) {
-        console.warn(chalk.yellow(`Warning: Failed to update cache for ${action.action}: ${error.message}`));
-    }
-};
-
-/* ==================== NETWORK REQUEST HANDLER ==================== */
-
-/**
- * Groups actions by resource ID to detect conflicts and sequence operations.
- * @returns {Object} { byResource: Map<recordId, actions[]>, assets: actions[] }
- */
-const groupActionsByResource = (actionQueue) => {
-    const byResource = new Map(); // recordId -> actions[]
-    const assets = []; // Asset operations (can run in parallel)
-
-    for (let i = 0; i < actionQueue.length; i++) {
-        const action = { ...actionQueue[i], originalIndex: i };
-
-        // Asset and Iris app operations don't need sequencing
-        if (['create_static_asset', 'delete_static_asset', 'create_folder', 'delete_folder', 'create_iris_app', 'update_iris_app', 'delete_iris_app'].includes(action.action)) {
-            assets.push(action);
-            continue;
-        }
-
-        // Code entity operations - group by recordId
-        const resourceId = action.recordId;
-        if (!resourceId) {
-            // Create actions without recordId yet - treat as unique resource
-            assets.push(action);
-            continue;
-        }
-
-        if (!byResource.has(resourceId)) {
-            byResource.set(resourceId, []);
-        }
-        byResource.get(resourceId).push(action);
-    }
-
-    return { byResource, assets };
-};
-
-/**
- * Resolves conflicts for a single resource and returns actions to execute in sequence.
- * Rules:
- * - If DELETE exists, drop all other actions (delete wins)
- * - If multiple UPDATEs exist, keep them in order (will execute sequentially)
- */
-const resolveResourceConflicts = (actions) => {
-    // Check if there's a delete action
-    const hasDelete = actions.some(a => a.action === 'delete');
-
-    if (hasDelete) {
-        // Delete wins - drop all other actions and only keep the delete
-        return actions.filter(a => a.action === 'delete');
-    }
-
-    // No delete - return all actions (they'll execute sequentially)
-    return actions;
-};
-
-/**
- * Executes actions for a single resource sequentially.
- */
-const executeResourceActions = async (instanceUrl, token, actions) => {
-    const results = [];
-
-    for (const action of actions) {
-        try {
-            let result;
-            switch (action.action) {
-                case "create":
-                    result = await handleCreateAction(instanceUrl, token, action);
-                    break;
-                case "update":
-                    result = await handleUpdateAction(instanceUrl, token, action);
-                    break;
-                case "delete":
-                    result = await handleDeleteAction(instanceUrl, token, action);
-                    break;
-                default:
-                    throw new Error(`Unknown action: ${action.action}`);
-            }
-            results.push({ index: action.originalIndex, action, result, success: true });
-        } catch (error) {
-            results.push({ index: action.originalIndex, action, error: error.message, success: false });
-        }
-    }
-
-    return results;
-};
-
-/**
- * Executes a single action and returns the result.
- */
-const executeAction = async (instanceUrl, token, action) => {
-    let result;
-    switch (action.action) {
-        case "create":
-            result = await handleCreateAction(instanceUrl, token, action);
-            break;
-        case "update":
-            result = await handleUpdateAction(instanceUrl, token, action);
-            break;
-        case "delete":
-            result = await handleDeleteAction(instanceUrl, token, action);
-            break;
-        case "create_static_asset":
-            result = await handleCreateStaticAssetAction(instanceUrl, token, action);
-            break;
-        case "delete_static_asset":
-            result = await handleDeleteStaticAssetAction(instanceUrl, token, action);
-            break;
-        case "create_folder":
-            result = await handleCreateFolderAction(instanceUrl, token, action);
-            break;
-        case "delete_folder":
-            result = await handleDeleteFolderAction(instanceUrl, token, action);
-            break;
-        case "create_iris_app":
-        case "update_iris_app":
-            result = await handlePublishIrisAppAction(instanceUrl, token, action);
-            break;
-        case "delete_iris_app":
-            result = await handleDeleteIrisAppAction(instanceUrl, token, action);
-            break;
-        default:
-            throw new Error(`Unknown action: ${action.action}`);
-    }
-    return result;
-};
-
-/**
- * Executes all actions sequentially (one at a time) with progress messages.
- */
-const performNetworkRequestSequential = async (actionQueue) => {
-    const { instanceUrl, token } = await ensureValidCredentials();
-
-    console.log(chalk.blue(`\n🔄 Sequential processing mode (${actionQueue.length} operations)\n`));
-
-    const results = [];
-    let successCount = 0;
-    let errorCount = 0;
-
-    for (let i = 0; i < actionQueue.length; i++) {
-        const action = { ...actionQueue[i], originalIndex: i };
-        const displayName = getActionDisplayName(action);
-
-        // Show progress message
-        console.log(chalk.gray(`[${i + 1}/${actionQueue.length}] Processing ${action.action.toUpperCase()} ${displayName}...`));
-
-        try {
-            const result = await executeAction(instanceUrl, token.value, action);
-            results.push({ index: i, action, result, success: true });
-
-            successCount++;
-            console.log(
-                chalk.green(`✓ [${i + 1}]`) +
-                ` ${chalk.yellow(action.action.toUpperCase())} ${chalk.cyan(displayName)} ` +
-                (result?.recordId ? chalk.magenta(result.recordId) : "")
-            );
-            await updateCacheAfterSuccess(action, result);
-        } catch (error) {
-            results.push({ index: i, action, error: error.message, success: false });
-
-            errorCount++;
-            console.log();
-            console.log(chalk.bgRed.bold.white('  ✖ Operation Failed  '));
-            console.log(chalk.redBright('─'.repeat(48)));
-            const actionPath = action.filePath || action.folderPath || action.folder || action.appPath || action.slug || 'unknown';
-            console.log(chalk.red.bold(`[${i + 1}] ${action.action.toUpperCase()} ${displayName} (${actionPath}):`));
-            console.log(formatMultilineError(error.message));
-            console.log(chalk.redBright('─'.repeat(48)));
-        }
-
-        console.log(); // Add spacing between operations
-    }
-
-    // Summary
-    console.log(chalk.blue("--- Publish Summary ---"));
-    console.log(chalk.green(`✓ Successful: ${successCount}`));
-    if (errorCount > 0) {
-        console.log(chalk.red(`✗ Failed: ${errorCount}`));
-    } else {
-        console.log(chalk.green("All operations completed successfully! 🎉"));
-    }
-};
-
-/**
- * Executes all actions in the queue with proper sequencing and conflict resolution (parallel mode).
- */
-const performNetworkRequestParallel = async (actionQueue) => {
-    const { instanceUrl, token } = await ensureValidCredentials();
-
-    // Group actions by resource
-    const { byResource, assets } = groupActionsByResource(actionQueue);
-
-    // Resolve conflicts for each resource
-    const sequencedCodeActions = [];
-    const droppedActions = [];
-
-    for (const [resourceId, actions] of byResource.entries()) {
-        const resolved = resolveResourceConflicts(actions);
-        sequencedCodeActions.push(resolved);
-
-        // Track dropped actions
-        const droppedCount = actions.length - resolved.length;
-        if (droppedCount > 0) {
-            const dropped = actions.filter(a => !resolved.includes(a));
-            droppedActions.push(...dropped);
-        }
-    }
-
-    // Log dropped actions
-    if (droppedActions.length > 0) {
-        console.log(chalk.yellow(`\n⚠️  Dropped ${droppedActions.length} redundant operation(s) due to delete:`));
-        droppedActions.forEach(action => {
-            console.log(chalk.gray(`   • ${action.action.toUpperCase()} on ${getActionDisplayName(action)} (superseded by DELETE)`));
-        });
-    }
-
-    // Execute asset operations in parallel (they don't conflict)
-    const assetPromises = assets.map(async (action) => {
-        try {
-            const result = await executeAction(instanceUrl, token.value, action);
-            return { index: action.originalIndex, action, result, success: true };
-        } catch (error) {
-            return { index: action.originalIndex, action, error: error.message, success: false };
-        }
-    });
-
-    // Execute code entity operations sequentially per resource (but resources in parallel)
-    const codePromises = sequencedCodeActions.map(actions =>
-        executeResourceActions(instanceUrl, token.value, actions)
-    );
-
-    // Wait for all operations
-    const assetResults = await Promise.allSettled(assetPromises);
-    const codeResults = await Promise.allSettled(codePromises);
-
-    // Flatten code results
-    const allCodeResults = codeResults
-        .filter(r => r.status === 'fulfilled')
-        .flatMap(r => r.value);
-
-    const allAssetResults = assetResults
-        .map(r => r.status === 'fulfilled' ? r.value : { status: 'rejected', reason: r.reason });
-
-    // Combine all results
-    const allResults = [...allCodeResults, ...allAssetResults];
-
-    // Sort by original index to maintain order
-    allResults.sort((a, b) => (a.index || 0) - (b.index || 0));
-
-    // Process and display results
-    let successCount = 0;
-    let errorCount = 0;
-
-    for (const result of allResults) {
-        if (result.success !== undefined) {
-            const { index, action, success, error, result: operationResult } = result;
-
-            if (success) {
-                successCount++;
-                const displayName = getActionDisplayName(action);
-                console.log(
-                    chalk.green(`✓ [${index + 1}]`) +
-                    ` ${chalk.yellow(action.action.toUpperCase())} ${chalk.cyan(displayName)} ` +
-                    (operationResult?.recordId ? chalk.magenta(operationResult.recordId) : "")
-                );
-                await updateCacheAfterSuccess(action, operationResult);
-            } else {
-                errorCount++;
-                console.log();
-                console.log(chalk.bgRed.bold.white('  ✖ Operation Failed  '));
-                console.log(chalk.redBright('─'.repeat(48)));
-                const actionPath = action.filePath || action.folderPath || action.folder || action.appPath || action.slug || 'unknown';
-                console.log(chalk.red.bold(`[${index + 1}] ${action.action.toUpperCase()} ${getActionDisplayName(action)} (${actionPath}):`));
-                console.log(formatMultilineError(error));
-                console.log(chalk.redBright('─'.repeat(48)));
-            }
-        } else if (result.status === 'rejected') {
-            errorCount++;
-            console.log();
-            console.log(chalk.bgRed.bold.white('  ✖ Unexpected Error  '));
-            console.log(chalk.redBright('─'.repeat(48)));
-            console.log(`${chalk.redBright('  •')} ${chalk.whiteBright(result.reason)}`);
-            console.log(chalk.redBright('─'.repeat(48)));
-        }
-    }
-
-    // Summary
-    console.log(chalk.blue("\n--- Publish Summary ---"));
-    console.log(chalk.green(`✓ Successful: ${successCount}`));
-    if (droppedActions.length > 0) {
-        console.log(chalk.yellow(`⊝ Dropped: ${droppedActions.length} (redundant)`));
-    }
-    if (errorCount > 0) {
-        console.log(chalk.red(`✗ Failed: ${errorCount}`));
-    } else {
-        console.log(chalk.green("All operations completed successfully! 🎉"));
-    }
-};
-
-/**
- * Executes all actions in the queue (dispatcher function).
- */
-const performNetworkRequest = async (actionQueue) => {
-    if (USE_SEQUENTIAL_PROCESSING) {
-        return await performNetworkRequestSequential(actionQueue);
-    } else {
-        return await performNetworkRequestParallel(actionQueue);
-    }
-};
-
-/* ==================== MAIN PUBLISH LOGIC ==================== */
-
-/**
- * Core publish logic - can be called from autopublish or directly.
- * @param {Object} options - Configuration options
- * @param {boolean} options.silent - If true, suppress summary output
- * @returns {Promise<{actionQueue: Array, hasChanges: boolean}>}
- */
-export const runPublish = async (options = {}) => {
-    const { silent = false } = options;
-
-    // Create progress tracker
-    const progress = silent ? null : new ProgressTracker('Publish to Magentrix');
-    if (progress) {
-        progress.addStep('auth', 'Authenticating...');
-        progress.addStep('load', 'Loading cached data...');
-        progress.addStep('scan', 'Scanning local files...');
-        progress.addStep('compare-assets', 'Comparing assets...', { hasProgress: true });
-        progress.addStep('compare-code', 'Comparing code entities...', { hasProgress: true });
-        progress.addStep('prepare', 'Preparing action queue...');
-        progress.start();
-        // Start first step immediately so UI shows up
-        progress.startStep('auth');
-    }
-
-    // Step 1: Authenticate
-    await ensureValidCredentials().catch((err) => {
-        if (progress) {
-            progress.abort(err.message);
-        } else if (!silent) {
-            console.error(chalk.red.bold("Authentication failed:"), chalk.white(err.message));
-        }
-        throw err;
-    });
-    if (progress) progress.completeStep('auth', '✓ Authenticated');
-
-    // Step 2: Load cached file state
-    if (progress) progress.startStep('load');
-
-    const loadStart = Date.now();
-    const hits = await config.searchObject({}, { filename: "base.json", global: false });
-    const cachedResults = hits?.[0]?.value || {};
-    const loadTime = Date.now() - loadStart;
-
-    if (!Object.keys(cachedResults).length) {
-        if (progress) {
-            progress.abort('No file cache found');
-        } else if (!silent) {
-            console.log(chalk.red.bold("No file cache found!"));
-            console.log(`Run ${chalk.cyan("magentrix pull")} to initialize your workspace.`);
-        }
-        throw new Error("No file cache found");
-    }
-
-    const mapStart = Date.now();
-    const cachedFiles = Object.values(cachedResults).map((c) => ({
-        ...c,
-        tag: c.recordId,
-        filePath: c.filePath || c.lastKnownPath,
-        type: c.type || c.Type,  // Normalize Type/type property
-    }));
-    const mapTime = Date.now() - mapStart;
-
-    if (progress) {
-        progress.completeStep('load', `✓ Loaded ${cachedFiles.length} entries (${loadTime}ms load, ${mapTime}ms map)`);
-    }
-
-    // Step 3: Scan local workspace (only whitelisted code entity directories)
-    if (progress) progress.startStep('scan');
-
-    const walkStart = Date.now();
-    // Only scan whitelisted directories for code entities (exclude Assets and iris-apps, handled separately)
-    const codeEntityDirs = ALLOWED_SRC_DIRS.filter(dir => dir !== 'Assets' && dir !== IRIS_APPS_DIR);
-    const localPathArrays = await Promise.all(
-        codeEntityDirs.map(dir => {
-            const dirPath = path.join(EXPORT_ROOT, dir);
-            return fs.existsSync(dirPath) ? walkFiles(dirPath) : Promise.resolve([]);
-        })
-    );
-    const localPaths = localPathArrays.flat();
-    const walkTime = Date.now() - walkStart;
-
-    const tagStart = Date.now();
-    const localFiles = await Promise.all(
-        localPaths.map(async (p) => {
-            try {
-                const tag = await getFileTag(p);
-                return { tag, path: p };
-            } catch {
-                return { tag: null, path: p };
-            }
-        })
-    );
-    const tagTime = Date.now() - tagStart;
-
-    if (progress) {
-        progress.completeStep('scan', `✓ Found ${localPaths.length} files (${walkTime}ms walk, ${tagTime}ms tags)`);
-    }
-
-    // Step 4: Create lookup maps
-    if (progress) progress.startStep('compare-assets');
-
-    const mapBuildStart = Date.now();
-    const cacheById = Object.fromEntries(cachedFiles.map((c) => [c.tag, c]));
-    const localById = Object.fromEntries(localFiles.filter((f) => f.tag).map((f) => [f.tag, f]));
-    const newLocalNoId = localFiles.filter((f) => !f.tag);
-    const allIds = new Set([...Object.keys(cacheById), ...Object.keys(localById)]);
-    const mapBuildTime = Date.now() - mapBuildStart;
-
-    const actionQueue = [];
-
-    // Step 5: Handle static asset files - Build fast lookup map first (O(n) instead of O(n²))
-    const assetWalkStart = Date.now();
-    const assetPaths = await walkFiles(path.join(EXPORT_ROOT, 'Assets'));
-    const assetWalkTime = Date.now() - assetWalkStart;
-
-    // Build a Set of normalized cached asset paths for O(1) lookup
-    const setStart = Date.now();
-    const cachedAssetPaths = new Set();
-    cachedFiles
-        .filter(cf => cf.type === 'File' || cf.type === 'Folder')
-        .forEach(cf => {
-            if (cf.lastKnownActualPath) {
-                cachedAssetPaths.add(path.normalize(path.resolve(cf.lastKnownActualPath)).toLowerCase());
-            }
-            if (cf.filePath) {
-                cachedAssetPaths.add(path.normalize(path.resolve(cf.filePath)).toLowerCase());
-            }
-            if (cf.lastKnownPath) {
-                cachedAssetPaths.add(path.normalize(path.resolve(cf.lastKnownPath)).toLowerCase());
-            }
-        });
-    const setTime = Date.now() - setStart;
-
-    // Now compare assets with O(1) lookup
-    for (let i = 0; i < assetPaths.length; i++) {
-        const assetPath = assetPaths[i];
-        const normalizedAssetPath = path.normalize(path.resolve(assetPath)).toLowerCase();
-
-        // Update progress every 100 files
-        if (progress && i % 100 === 0) {
-            progress.updateProgress('compare-assets', i, assetPaths.length, `Checking ${i}/${assetPaths.length} assets`);
-        }
-
-        // O(1) lookup instead of O(n) find()
-        if (cachedAssetPaths.has(normalizedAssetPath)) {
-            continue;
-        }
-
-        actionQueue.push({
-            action: "create_static_asset",
-            folder: toApiPath(assetPath),
-            filePath: assetPath
-        });
-    }
-
-    if (progress) {
-        progress.completeStep('compare-assets', `✓ Compared ${assetPaths.length} assets (walk:${assetWalkTime}ms, set:${setTime}ms, map:${mapBuildTime}ms)`);
-    }
-
-    // Step 6: Handle folder creation and deletion - Also optimized with Set
-    const assetsDir = path.join(EXPORT_ROOT, 'Assets');
-    if (fs.existsSync(assetsDir)) {
-        const localFolders = walkFolders(assetsDir);
-        const cachedFolders = cachedFiles
-            .filter(c => c.type === 'Folder' && (c.filePath || c.lastKnownPath || c.lastKnownActualPath));
-
-        // Build Set of cached folder paths for O(1) lookup
-        const cachedFolderPaths = new Set();
-        cachedFolders.forEach(cf => {
-            if (cf.lastKnownActualPath) {
-                cachedFolderPaths.add(path.normalize(path.resolve(cf.lastKnownActualPath)).toLowerCase());
-            }
-            if (cf.lastKnownPath) {
-                cachedFolderPaths.add(path.normalize(path.resolve(cf.lastKnownPath)).toLowerCase());
-            }
-            if (cf.filePath) {
-                cachedFolderPaths.add(path.normalize(path.resolve(cf.filePath)).toLowerCase());
-            }
-        });
-
-        // Build Set of local folder paths for O(1) lookup
-        const localFolderPaths = new Set(
-            localFolders.map(lf => path.normalize(path.resolve(lf)).toLowerCase())
-        );
-
-        // New folders - O(1) lookup
-        for (const folderPath of localFolders) {
-            if (!folderPath) continue;
-
-            const normalizedFolderPath = path.normalize(path.resolve(folderPath)).toLowerCase();
-
-            if (cachedFolderPaths.has(normalizedFolderPath)) {
-                continue;
-            }
-
-            const parentDir = path.dirname(folderPath);
-            if (!parentDir || parentDir === '.' || parentDir === folderPath) continue;
-
-            actionQueue.push({
-                action: "create_folder",
-                folderPath: folderPath,
-                parentPath: toApiFolderPath(parentDir),
-                folderName: path.basename(folderPath)
-            });
-        }
-
-        // Deleted folders - O(1) lookup
-        for (const cachedFolder of cachedFolders) {
-            const cachedPath = cachedFolder.lastKnownActualPath || cachedFolder.lastKnownPath || cachedFolder.filePath;
-            if (!cachedPath || typeof cachedPath !== 'string') continue;
-
-            const normalizedCachedPath = path.normalize(path.resolve(cachedPath)).toLowerCase();
-
-            if (localFolderPaths.has(normalizedCachedPath)) {
-                continue;
-            }
-
-            const parentDir = path.dirname(cachedPath);
-            if (!parentDir || parentDir === '.' || parentDir === cachedPath) continue;
-
-            actionQueue.push({
-                action: "delete_folder",
-                folderPath: cachedPath,
-                parentPath: toApiFolderPath(parentDir),
-                folderName: path.basename(cachedPath),
-                baseKey: cachedFolder.tag // The original base.json key for correct cache cleanup
-            });
-        }
-    }
-
-    // Step 7: Process code entities (ActiveClass/ActivePage) and static assets
-    if (progress) progress.startStep('compare-code');
-
-    const allIdsArray = Array.from(allIds);
-    for (let idx = 0; idx < allIdsArray.length; idx++) {
-        const id = allIdsArray[idx];
-
-        // Update progress every 50 items
-        if (progress && idx % 50 === 0) {
-            progress.updateProgress('compare-code', idx, allIdsArray.length, `Checking ${idx}/${allIdsArray.length} entities`);
-        }
-
-        try {
-            const cacheFile = cacheById[id];
-            const curFile = localById[id];
-
-            // Skip folders - they're handled separately
-            if (cacheFile?.type === 'Folder') continue;
-
-            // Skip Iris apps - they're handled separately (check both type and ID prefix)
-            if (cacheFile?.type === 'IrisApp' || id.startsWith('iris-app:')) continue;
-
-            // Handle static asset files
-            if (cacheFile?.type === 'File') {
-                // Use lastKnownActualPath which has the correct path (e.g., "src/Assets/...")
-                const actualPath = cacheFile.lastKnownActualPath || cacheFile.filePath;
-                const localAssetExists = fs.existsSync(actualPath);
-
-                if (!localAssetExists) {
-                    actionQueue.push({
-                        action: 'delete_static_asset',
-                        folder: toApiPath(actualPath),
-                        names: [path.basename(actualPath)],
-                        filePath: actualPath, // Store actual file path for filtering
-                        baseKey: id // The original base.json key for correct cache cleanup
-                    });
-                    continue;
-                }
-
-                const contentHash = sha256(fs.readFileSync(actualPath, 'utf-8'));
-                if (contentHash !== cacheFile.contentHash) {
-                    actionQueue.push({
-                        action: "create_static_asset",
-                        folder: toApiPath(actualPath),
-                        filePath: actualPath
-                    });
-                }
-                continue;
-            }
-
-            // Handle code entity deletion
-            if (cacheFile && !curFile) {
-                const { type, entity } = inferMeta(path.resolve(cacheFile.lastKnownPath));
-                actionQueue.push({
-                    action: "delete",
-                    recordId: id,
-                    filePath: cacheFile.lastKnownPath,
-                    type,
-                    entity,
-                });
-                continue;
-            }
-
-            // Handle code entity creation
-            if (!cacheFile && curFile) {
-                const safe = readFileSafe(curFile.path);
-                if (!safe) continue;
-
-                const { content, hash } = safe;
-                const { type, entity, contentField } = inferMeta(path.resolve(curFile.path));
-
-                actionQueue.push({
-                    action: "create",
-                    filePath: curFile.path,
-                    recordId: id || null,
-                    type,
-                    entity,
-                    fields: { [contentField]: content },
-                    contentHash: hash,
-                });
-                continue;
-            }
-
-            // Handle code entity update
-            if (cacheFile && curFile) {
-                const safe = readFileSafe(curFile.path);
-                if (!safe) continue;
-
-                const { content, hash } = safe;
-                // Check both paths - only consider renamed if NEITHER matches current path
-                // This prevents false positives from stale/corrupted tracking data
-                const resolvedCurPath = path.resolve(curFile.path);
-                const matchesActualPath = cacheFile.lastKnownActualPath === resolvedCurPath;
-                const matchesExpectedPath = cacheFile.lastKnownPath === resolvedCurPath;
-                const renamed = !matchesActualPath && !matchesExpectedPath;
-                const contentChanged = hash !== cacheFile.contentHash;
-
-                if (renamed || contentChanged) {
-                    const { type, entity, contentField } = inferMeta(path.resolve(curFile.path));
-
-                    actionQueue.push({
-                        action: "update",
-                        recordId: id,
-                        type,
-                        entity,
-                        fields: { [contentField]: content },
-                        renamed,
-                        oldPath: cacheFile.lastKnownActualPath || cacheFile.lastKnownPath,
-                        filePath: curFile.path,
-                    });
-                }
-            }
-        } catch (err) {
-            if (!silent) {
-                console.error(chalk.yellow(`Warning: Error processing file with ID ${id}:`), err.message);
-            }
-        }
-    }
-
-    if (progress) {
-        progress.completeStep('compare-code', `✓ Compared ${allIdsArray.length} code entities`);
-    }
-
-    // Step 7b: Scan and compare Iris apps
-    const irisAppsPath = path.join(EXPORT_ROOT, IRIS_APPS_DIR);
-
-    // Get cached Iris apps (always check, even if local folder doesn't exist)
-    // Also include entries with iris-app: prefix in case type wasn't properly set
-    const cachedIrisApps = cachedFiles
-        .filter(cf => cf.type === 'IrisApp' || (cf.tag && cf.tag.startsWith('iris-app:')))
-        .map(cf => {
-            // Extract slug from folderName, or from the ID (iris-app:<slug>)
-            const slug = cf.folderName || (cf.tag && cf.tag.startsWith('iris-app:') ? cf.tag.replace('iris-app:', '') : null);
-            return {
-                slug,
-                appName: cf.appName || slug,
-                modifiedOn: cf.modifiedOn,
-                contentHash: cf.contentHash || null  // Track content hash for change detection
-            };
-        })
-        .filter(app => app.slug); // Filter out any entries without a valid slug
-
-    // Get local Iris apps (empty if folder doesn't exist)
-    const localIrisApps = fs.existsSync(irisAppsPath)
-        ? fs.readdirSync(irisAppsPath, { withFileTypes: true })
-            .filter(d => d.isDirectory())
-            .map(d => d.name)
-        : [];
-
-    const cachedIrisSlugs = new Set(cachedIrisApps.map(a => a.slug));
-    const localIrisSlugs = new Set(localIrisApps);
-
-    // Detect new and modified Iris apps
-    for (const slug of localIrisApps) {
-        const appPath = path.join(irisAppsPath, slug);
-
-        // Validate the app folder has required files
-        const validation = validateIrisAppFolder(appPath);
-        if (!validation.valid) {
-            if (!silent) {
-                console.log(chalk.yellow(`⚠ Skipping invalid Iris app '${slug}': ${validation.errors.join(', ')}`));
-            }
-            continue;
-        }
-
-        // Get app metadata from linked project config (stored globally) or use slug
-        const linkedProjects = getLinkedProjects();
-        const linkedProject = linkedProjects.find(p => p.slug === slug);
-        const appName = linkedProject?.appName || slug;
-        const appDescription = linkedProject?.appDescription || null;
-        const appIconId = linkedProject?.appIconId || null;
-
-        // Calculate content hash for change detection
-        const currentHash = hashIrisAppFolder(appPath);
-
-        // Check if this is a new or existing app
-        const isNew = !cachedIrisSlugs.has(slug);
-
-        if (isNew) {
-            actionQueue.push({
-                action: 'create_iris_app',
-                slug,
-                appName,
-                appDescription,
-                appIconId,
-                appPath,
-                contentHash: currentHash
-            });
-        } else {
-            // Only update if content has changed
-            const cachedApp = cachedIrisApps.find(a => a.slug === slug);
-            const contentChanged = !cachedApp?.contentHash || cachedApp.contentHash !== currentHash;
-
-            if (contentChanged) {
-                actionQueue.push({
-                    action: 'update_iris_app',
-                    slug,
-                    appName: linkedProject?.appName || cachedApp?.appName || slug,
-                    appDescription,
-                    appIconId,
-                    appPath,
-                    contentHash: currentHash
-                });
-            }
-        }
-    }
-
-    // Detect deleted Iris apps (works even if iris-apps folder doesn't exist)
-    for (const cachedApp of cachedIrisApps) {
-        if (!localIrisSlugs.has(cachedApp.slug)) {
-            actionQueue.push({
-                action: 'delete_iris_app',
-                slug: cachedApp.slug
-            });
-        }
-    }
-
-    // Step 8: Handle brand-new, tag-less files
-    if (progress) progress.startStep('prepare');
-
-    for (const f of newLocalNoId) {
-        const safe = readFileSafe(f.path);
-        if (!safe) {
-            if (!silent) {
-                console.log(chalk.yellow(`Skipping unreadable file: ${f.path}`));
-            }
-            continue;
-        }
-
-        const { content, hash } = safe;
-        const { type, entity, contentField } = inferMeta(path.resolve(f.path));
-
-        actionQueue.push({
-            action: "create",
-            filePath: f.path,
-            recordId: null,
-            type,
-            entity,
-            fields: { [contentField]: content },
-            contentHash: hash,
-        });
-    }
-
-    // Step 9: Filter out redundant file and folder deletions
-    const foldersBeingDeleted = actionQueue
-        .filter(a => a.action === 'delete_folder')
-        .map(a => a.folderPath);
-
-    const filteredActionQueue = actionQueue.filter(action => {
-        // Filter out files inside folders being deleted
-        if (action.action === 'delete_static_asset' && action.filePath) {
-            const fileDir = path.dirname(action.filePath);
-            for (const deletedFolder of foldersBeingDeleted) {
-                const normalizedFileDir = path.normalize(fileDir);
-                const normalizedDeletedFolder = path.normalize(deletedFolder);
-
-                if (normalizedFileDir === normalizedDeletedFolder ||
-                    normalizedFileDir.startsWith(normalizedDeletedFolder + path.sep)) {
-                    return false; // Skip - covered by folder deletion
-                }
-            }
-        }
-
-        // Filter out child folders inside folders being deleted
-        if (action.action === 'delete_folder' && action.folderPath) {
-            for (const deletedFolder of foldersBeingDeleted) {
-                // Don't compare a folder to itself
-                if (action.folderPath === deletedFolder) continue;
-
-                const normalizedChildFolder = path.normalize(action.folderPath);
-                const normalizedParentFolder = path.normalize(deletedFolder);
-
-                // Check if this folder is inside another folder being deleted
-                if (normalizedChildFolder.startsWith(normalizedParentFolder + path.sep)) {
-                    return false; // Skip - covered by parent folder deletion
-                }
-            }
-        }
-
-        return true;
-    });
-
-    if (progress) {
-        progress.completeStep('prepare', `✓ Prepared ${filteredActionQueue.length} actions`);
-        progress.finish();
-    }
-
-    // Step 10: Display and execute action queue
-    if (!silent) {
-        console.log(chalk.blue("\n--- Publish Action Queue ---"));
-        if (!filteredActionQueue.length) {
-            console.log(chalk.green("All files are in sync — nothing to publish!"));
-        } else {
-            filteredActionQueue.forEach((a, i) => {
-                const num = chalk.green(`[${i + 1}]`);
-                const act = chalk.yellow(a.action.toUpperCase());
-
-                let type, displayPath, label;
-                if (a.slug) {
-                    // Iris app action
-                    type = chalk.cyan(`${a.appName || a.slug}`);
-                    displayPath = a.appPath || a.slug;
-                    label = "App";
-                } else if (a.folderName) {
-                    type = chalk.cyan(a.folderName);
-                    displayPath = a.folderPath;
-                    label = "Folder";
-                } else if (a.names) {
-                    type = chalk.cyan(a.names.join(", "));
-                    displayPath = a.folder;
-                    label = "File";
-                } else if (a.filePath) {
-                    type = chalk.cyan(a.type || path.basename(a.filePath));
-                    displayPath = a.filePath;
-                    label = a.type ? "Type" : "File";
-                } else {
-                    type = chalk.cyan(a.type || "Unknown");
-                    displayPath = a.folder || "Unknown";
-                    label = "File";
-                }
-
-                const idInfo = a.recordId ? ` ${chalk.magenta(a.recordId)}` : "";
-                const renameInfo = a.renamed
-                    ? ` → ${chalk.gray(a.oldPath)} ${chalk.white("→")} ${chalk.gray(a.filePath)}`
-                    : "";
-
-                console.log(`${num} ${act} | ${label}: ${type}${idInfo}${renameInfo} (${displayPath})`);
-            });
-
-            console.log(chalk.blue("\n--- Publishing Changes ---"));
-        }
-    }
-
-    // Execute actions
-    if (filteredActionQueue.length > 0) {
-        if (silent) {
-            await performNetworkRequest(filteredActionQueue);
-        } else {
-            await withSpinner(
-                "Working...",
-                async () => {
-                    await performNetworkRequest(filteredActionQueue)
-                },
-                { showCompletion: false }
-            );
-        }
-    }
-
-    return {
-        actionQueue: filteredActionQueue,
-        hasChanges: filteredActionQueue.length > 0
-    };
-};
-
-/**
- * CLI command wrapper for publish.
- */
-export const publish = async () => {
-    process.stdout.write("\x1Bc"); // clear console
-
-    try {
-        await runPublish({ silent: false });
-    } catch (err) {
-        console.error(chalk.red.bold("Publish failed:"), err.message);
-        process.exit(1);
-    }
-};
+import { walkFiles } from "../utils/cacher.js";
+import { ensureValidCredentials } from "../utils/cli/helpers/ensureCredentials.js";
+import Config from "../utils/config.js";
+import { withSpinner } from "../utils/spinner.js";
+import { ProgressTracker } from "../utils/progress.js";
+import fs from "fs";
+import path from "path";
+import chalk from "chalk";
+import {
+    ENTITY_FIELD_MAP,
+    ENTITY_TYPE_MAP,
+    EXPORT_ROOT,
+    TYPE_DIR_MAP,
+    IRIS_APPS_DIR,
+    ALLOWED_SRC_DIRS,
+} from "../vars/global.js";
+import { getFileTag, setFileTag } from "../utils/filetag.js";
+import { sha256 } from "../utils/hash.js";
+import { createEntity } from "../utils/magentrix/api/createEntity.js";
+import { updateEntity } from "../utils/magentrix/api/updateEntity.js";
+import { deleteEntity } from "../utils/magentrix/api/deleteEntity.js";
+import { removeFromBase, updateBase } from "../utils/updateFileBase.js";
+import { deleteAsset, uploadAsset, createFolder } from "../utils/magentrix/api/assets.js";
+import { toApiPath, toApiFolderPath } from "../utils/assetPaths.js";
+import { publishApp } from "../utils/magentrix/api/iris.js";
+import { createIrisZip, hashIrisAppFolder } from "../utils/iris/zipper.js";
+import { validateIrisAppFolder } from "../utils/iris/validator.js";
+import { getLinkedProjects } from "../utils/iris/linker.js";
+import { deleteIrisAppFromServer } from "../utils/iris/deleteHelper.js";
+
+const config = new Config();
+
+/* ==================== CONFIGURATION ==================== */
+
+/**
+ * Set to true to process all operations sequentially (one at a time).
+ * Set to false to process operations in parallel with intelligent grouping.
+ *
+ * Sequential mode is slower but avoids any potential race conditions or
+ * server-side rate limiting issues.
+ */
+const USE_SEQUENTIAL_PROCESSING = true;
+
+/* ==================== UTILITY FUNCTIONS ==================== */
+
+/**
+ * Infers Magentrix entity metadata from a file path by walking up the directory tree.
+ * @param {string} filePath - The file path to analyze
+ * @returns {Object} { type, entity, contentField } for Magentrix API
+ */
+const inferMeta = (filePath) => {
+    let currentPath = path.dirname(filePath);
+    const exportRootAbs = path.resolve(EXPORT_ROOT);
+
+    while (currentPath.startsWith(exportRootAbs)) {
+        const folderName = path.basename(currentPath);
+        const type = Object.keys(TYPE_DIR_MAP).find(
+            (k) => TYPE_DIR_MAP[k].directory === folderName
+        );
+
+        if (type) {
+            return {
+                type,
+                entity: ENTITY_TYPE_MAP[type],
+                contentField: ENTITY_FIELD_MAP[type],
+            };
+        }
+
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) break; // Reached root
+        currentPath = parentPath;
+    }
+
+    return { type: undefined, entity: undefined, contentField: undefined };
+};
+
+/**
+ * Safely reads file content and computes hash.
+ * @param {string} filePath - Path to the file
+ * @returns {Object|null} { content, hash } or null on error
+ */
+const readFileSafe = (filePath) => {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        return { content, hash: sha256(content) };
+    } catch (err) {
+        console.error(chalk.red.bold("Error:") + " Unable to read file " + chalk.white.bold(filePath));
+        console.error(chalk.gray("→ Please verify the file exists and you have read permissions."));
+        return null;
+    }
+};
+
+/**
+ * Formats multiline error messages with proper indentation.
+ */
+const formatMultilineError = (err) => {
+    const lines = String(err).split(/\r?\n/);
+    return lines
+        .map((line, i) => {
+            const prefix = i === 0 ? `${chalk.redBright('  •')} ` : '    ';
+            return prefix + chalk.whiteBright(line);
+        })
+        .join('\n');
+};
+
+/**
+ * Recursively walks a directory and returns all subdirectory paths.
+ */
+const walkFolders = (dir) => {
+    if (!fs.existsSync(dir)) return [];
+
+    const folders = [];
+    const items = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const item of items) {
+        if (item.isDirectory()) {
+            const fullPath = path.join(dir, item.name);
+            folders.push(fullPath);
+            folders.push(...walkFolders(fullPath));
+        }
+    }
+
+    return folders;
+};
+
+/**
+ * Gets display name for an action in log messages.
+ */
+const getActionDisplayName = (action) => {
+    // Iris app actions
+    if (action.slug) return `${action.appName || action.slug} (${action.slug})`;
+    if (action.folderName) return action.folderName;
+    if (action.names) return action.names.join(", ");
+    if (action.type) return action.type;
+    if (action.filePath) return path.basename(action.filePath);
+    return '';
+};
+
+/* ==================== ACTION HANDLERS ==================== */
+
+/**
+ * Handles CREATE action for code entities (ActiveClass/ActivePage).
+ */
+const handleCreateAction = async (instanceUrl, apiKey, action) => {
+    const data = {
+        Name: path.basename(action.filePath, path.extname(action.filePath)),
+        Type: action.type,
+        ...action.fields
+    };
+
+    const result = await createEntity(instanceUrl, apiKey, action.entity, data);
+    return { recordId: result.recordId || result.id };
+};
+
+/**
+ * Handles UPDATE action for code entities (ActiveClass/ActivePage).
+ */
+const handleUpdateAction = async (instanceUrl, apiKey, action) => {
+    const data = { ...action.fields };
+
+    if (action.renamed) {
+        data.Name = path.basename(action.filePath, path.extname(action.filePath));
+    }
+
+    await updateEntity(instanceUrl, apiKey, action.entity, action.recordId, data);
+    return { recordId: action.recordId };
+};
+
+/**
+ * Handles DELETE action for code entities (ActiveClass/ActivePage).
+ */
+const handleDeleteAction = async (instanceUrl, apiKey, action) => {
+    return await deleteEntity(instanceUrl, apiKey, action.entity, action.recordId);
+};
+
+/**
+ * Handles CREATE_STATIC_ASSET action.
+ */
+const handleCreateStaticAssetAction = async (instanceUrl, apiKey, action) => {
+    const response = await uploadAsset(instanceUrl, apiKey, `/${action.folder}`, [action.filePath]);
+    if (response?.error) throw new Error(response.error);
+    return response;
+};
+
+/**
+ * Handles DELETE_STATIC_ASSET action.
+ */
+const handleDeleteStaticAssetAction = async (instanceUrl, apiKey, action) => {
+    try {
+        const response = await deleteAsset(instanceUrl, apiKey, `/${action.folder}`, action.names);
+        return response;
+    } catch (error) {
+        // Check if this is a "not found" error
+        const errorMessage = error?.message || String(error);
+        const errorLower = errorMessage.toLowerCase();
+        const isNotFound = errorLower.includes('404') ||
+            errorLower.includes('not found') ||
+            errorLower.includes('item not found');
+
+        if (isNotFound) {
+            // Clean up base.json since file doesn't exist on server
+            // Use the original base.json key if available (avoids path format mismatches)
+            if (action.baseKey) {
+                removeFromBase(action.baseKey);
+            } else {
+                for (const name of action.names) {
+                    const filePath = action.filePath || `${EXPORT_ROOT}/${action.folder}/${name}`;
+                    removeFromBase(filePath);
+                }
+            }
+            return { cleanedFromCache: true };
+        }
+
+        // Other errors should still fail
+        throw error;
+    }
+};
+
+/**
+ * Handles CREATE_FOLDER action.
+ */
+const handleCreateFolderAction = async (instanceUrl, apiKey, action) => {
+    try {
+        const response = await createFolder(instanceUrl, apiKey, action.parentPath, action.folderName);
+        return response;
+    } catch (error) {
+        // Check if folder already exists (likely created by file upload)
+        const errorMessage = error?.message || String(error);
+        const errorLower = errorMessage.toLowerCase();
+        const alreadyExists = errorLower.includes('already exists') ||
+            errorLower.includes('folder exists') ||
+            errorLower.includes('duplicate');
+
+        if (alreadyExists) {
+            // Folder already exists, update cache and treat as success
+            return { alreadyExisted: true };
+        }
+
+        // Other errors should still fail
+        throw error;
+    }
+};
+
+/**
+ * Handles DELETE_FOLDER action.
+ */
+const handleDeleteFolderAction = async (instanceUrl, apiKey, action) => {
+    try {
+        const response = await deleteAsset(instanceUrl, apiKey, action.parentPath, [action.folderName]);
+        return response;
+    } catch (error) {
+        // Check if this is a "not found" error
+        const errorMessage = error?.message || String(error);
+        const errorLower = errorMessage.toLowerCase();
+        const isNotFound = errorLower.includes('404') ||
+            errorLower.includes('not found') ||
+            errorLower.includes('item not found');
+
+        if (isNotFound) {
+            // Clean up base.json since folder doesn't exist on server
+            // Use original base.json key if available (avoids path format mismatches)
+            removeFromBase(action.baseKey || action.folderPath);
+
+            // Also remove all files and subfolders inside this folder from base
+            const hits = await config.searchObject({}, { filename: "base.json", global: false });
+            const cachedResults = hits?.[0]?.value || {};
+
+            for (const [recordId, cachedEntry] of Object.entries(cachedResults)) {
+                // Check all possible path fields
+                const entryPath = cachedEntry.lastKnownActualPath || cachedEntry.filePath || cachedEntry.lastKnownPath;
+                if (entryPath && typeof entryPath === 'string') {
+                    const normalizedEntryPath = path.normalize(path.resolve(entryPath)).toLowerCase();
+                    const normalizedFolderPath = path.normalize(path.resolve(action.folderPath)).toLowerCase();
+
+                    // Check if this entry is inside the deleted folder
+                    if (normalizedEntryPath.startsWith(normalizedFolderPath + path.sep) ||
+                        normalizedEntryPath === normalizedFolderPath) {
+                        removeFromBase(recordId);
+                    }
+                }
+            }
+
+            return { cleanedFromCache: true };
+        }
+
+        // Other errors should still fail
+        throw error;
+    }
+};
+
+/**
+ * Handles CREATE_IRIS_APP or UPDATE_IRIS_APP action.
+ */
+const handlePublishIrisAppAction = async (instanceUrl, apiKey, action) => {
+    // Create zip from the app folder
+    const zipBuffer = await createIrisZip(action.appPath, action.slug);
+
+    // For updates, don't send app-name/description/icon to avoid triggering
+    // metadata modification that may require permissions the user doesn't have.
+    // The server already has the correct metadata from the original create.
+    // For creates, send all metadata so the app is properly registered.
+    const isUpdate = action.action === 'update_iris_app';
+
+    const response = await publishApp(
+        instanceUrl,
+        apiKey,
+        zipBuffer,
+        `${action.slug}.zip`,
+        isUpdate ? null : action.appName,
+        isUpdate ? {} : {
+            appDescription: action.appDescription,
+            appIconId: action.appIconId
+        }
+    );
+
+    return response;
+};
+
+/**
+ * Handles DELETE_IRIS_APP action.
+ */
+const handleDeleteIrisAppAction = async (instanceUrl, apiKey, action) => {
+    // Use shared delete utility for consistency
+    return await deleteIrisAppFromServer(instanceUrl, apiKey, action.slug, {
+        updateCache: true  // Cache will be updated by the utility
+    });
+};
+
+/**
+ * Synchronizes class name in content with filename, or vice versa.
+ */
+const syncClassAndFileNames = (action, recordId) => {
+    // Only for ActiveClass
+    if (action.entity !== 'ActiveClass') return;
+
+    const filePath = action.filePath;
+    // If file was deleted or doesn't exist, skip
+    if (!fs.existsSync(filePath)) return;
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const filename = path.basename(filePath, path.extname(filePath));
+
+    // Regex to find class/interface/enum name
+    // Matches: public class Name, public interface Name, public enum Name
+    // We assume standard formatting
+    const classRegex = /public\s+(?:class|interface|enum)\s+(\w+)/;
+    const match = content.match(classRegex);
+
+    if (match) {
+        const classNameInContent = match[1];
+
+        if (classNameInContent !== filename) {
+            // Mismatch detected
+
+            // Case 1: File was renamed (action.renamed is true) -> Update content
+            if (action.renamed) {
+                const newContent = content.replace(classRegex, (fullMatch, name) => {
+                    return fullMatch.replace(name, filename);
+                });
+                fs.writeFileSync(filePath, newContent);
+                console.log(chalk.cyan(`  ↻ Updated class name in file to: ${filename}`));
+
+                // Update cache with new content hash
+                updateBase(filePath, { Id: recordId, Type: 'ActiveClass' });
+            }
+            // Case 2: Content was updated (action.renamed is false) -> Rename file
+            else {
+                // Rename file to match class name
+                const dir = path.dirname(filePath);
+                const ext = path.extname(filePath);
+                const newFilename = `${classNameInContent}${ext}`;
+                const newFilePath = path.join(dir, newFilename);
+
+                if (fs.existsSync(newFilePath)) {
+                    console.warn(chalk.yellow(`  ⚠️  Cannot rename ${filename} to ${classNameInContent}: File already exists.`));
+                    return;
+                }
+
+                try {
+                    fs.renameSync(filePath, newFilePath);
+                    console.log(chalk.cyan(`  ↻ Renamed file to match class: ${newFilename}`));
+
+                    // Update cache: update the entry for this recordId to point to new path
+                    updateBase(newFilePath, { Id: recordId, Type: 'ActiveClass' }, newFilePath);
+                } catch (err) {
+                    console.warn(chalk.yellow(`  ⚠️  Failed to rename file: ${err.message}`));
+                }
+            }
+        }
+    }
+};
+
+/**
+ * Updates cache after successful operations.
+ */
+const updateCacheAfterSuccess = async (action, operationResult) => {
+    try {
+        // Sync class names/filenames if needed (Bug 2 Fix)
+        if (action.action === 'update' && operationResult?.recordId) {
+            syncClassAndFileNames(action, operationResult.recordId);
+        }
+
+        switch (action.action) {
+            case "create": {
+                const createSnapshot = action.fields && Object.values(action.fields)[0]
+                    ? { content: Object.values(action.fields)[0], hash: action.contentHash }
+                    : null;
+                await setFileTag(action.filePath, operationResult.recordId);
+                updateBase(
+                    action.filePath,
+                    { Id: operationResult.recordId, Type: action.type },
+                    '',
+                    createSnapshot
+                );
+                break;
+            }
+
+            case "update": {
+                const updateSnapshot = action.fields && Object.values(action.fields)[0]
+                    ? { content: Object.values(action.fields)[0], hash: sha256(Object.values(action.fields)[0]) }
+                    : null;
+                const type = Object.keys(ENTITY_TYPE_MAP).find(key => ENTITY_TYPE_MAP[key] === action.entity);
+                updateBase(
+                    action.filePath,
+                    { Id: action.recordId, Type: type },
+                    '',
+                    updateSnapshot
+                );
+                break;
+            }
+
+            case "delete":
+                removeFromBase(action.recordId);
+                break;
+
+            case "delete_static_asset":
+                // Skip if already cleaned from cache during 404 handling
+                if (!operationResult?.cleanedFromCache) {
+                    // Use the original base.json key if available (avoids path format mismatches)
+                    if (action.baseKey) {
+                        removeFromBase(action.baseKey);
+                    } else {
+                        for (const name of action.names) {
+                            const filePath = action.filePath || `${EXPORT_ROOT}/${action.folder}/${name}`;
+                            removeFromBase(filePath);
+                        }
+                    }
+                }
+                break;
+
+            case "create_static_asset":
+                updateBase(action.filePath, { Id: action.filePath, Type: "File" });
+                break;
+
+            case "create_folder":
+                updateBase(action.folderPath, { Id: action.folderPath, Type: "Folder" });
+                break;
+
+            case "delete_folder": {
+                // Skip if already cleaned from cache during 404 handling
+                if (!operationResult?.cleanedFromCache) {
+                    // Remove the folder itself from base using the original base.json key
+                    removeFromBase(action.baseKey || action.folderPath);
+
+                    // Also remove all files and subfolders inside this folder from base
+                    const hits = await config.searchObject({}, { filename: "base.json", global: false });
+                    const cachedResults = hits?.[0]?.value || {};
+
+                    for (const [recordId, cachedEntry] of Object.entries(cachedResults)) {
+                        // Check all possible path fields
+                        const entryPath = cachedEntry.lastKnownActualPath || cachedEntry.filePath || cachedEntry.lastKnownPath;
+                        if (entryPath && typeof entryPath === 'string') {
+                            const normalizedEntryPath = path.normalize(path.resolve(entryPath)).toLowerCase();
+                            const normalizedFolderPath = path.normalize(path.resolve(action.folderPath)).toLowerCase();
+
+                            // Check if this entry is inside the deleted folder
+                            if (normalizedEntryPath.startsWith(normalizedFolderPath + path.sep) ||
+                                normalizedEntryPath === normalizedFolderPath) {
+                                removeFromBase(recordId);
+                            }
+                        }
+                    }
+                }
+                break;
+            }
+
+            case "create_iris_app":
+            case "update_iris_app": {
+                // Update base.json with new/updated Iris app info including content hash
+                updateBase(action.appPath, {
+                    Id: `iris-app:${action.slug}`,
+                    Type: 'IrisApp',
+                    folderName: action.slug,
+                    appName: action.appName,
+                    modifiedOn: new Date().toISOString(),
+                    contentHash: action.contentHash  // Store hash for change detection
+                }, action.appPath);
+                break;
+            }
+
+            case "delete_iris_app": {
+                // Skip if already cleaned from cache during 404 handling
+                if (!operationResult?.cleanedFromCache) {
+                    removeFromBase(`iris-app:${action.slug}`);
+                }
+                break;
+            }
+        }
+    } catch (error) {
+        console.warn(chalk.yellow(`Warning: Failed to update cache for ${action.action}: ${error.message}`));
+    }
+};
+
+/* ==================== NETWORK REQUEST HANDLER ==================== */
+
+/**
+ * Groups actions by resource ID to detect conflicts and sequence operations.
+ * @returns {Object} { byResource: Map<recordId, actions[]>, assets: actions[] }
+ */
+const groupActionsByResource = (actionQueue) => {
+    const byResource = new Map(); // recordId -> actions[]
+    const assets = []; // Asset operations (can run in parallel)
+
+    for (let i = 0; i < actionQueue.length; i++) {
+        const action = { ...actionQueue[i], originalIndex: i };
+
+        // Asset and Iris app operations don't need sequencing
+        if (['create_static_asset', 'delete_static_asset', 'create_folder', 'delete_folder', 'create_iris_app', 'update_iris_app', 'delete_iris_app'].includes(action.action)) {
+            assets.push(action);
+            continue;
+        }
+
+        // Code entity operations - group by recordId
+        const resourceId = action.recordId;
+        if (!resourceId) {
+            // Create actions without recordId yet - treat as unique resource
+            assets.push(action);
+            continue;
+        }
+
+        if (!byResource.has(resourceId)) {
+            byResource.set(resourceId, []);
+        }
+        byResource.get(resourceId).push(action);
+    }
+
+    return { byResource, assets };
+};
+
+/**
+ * Resolves conflicts for a single resource and returns actions to execute in sequence.
+ * Rules:
+ * - If DELETE exists, drop all other actions (delete wins)
+ * - If multiple UPDATEs exist, keep them in order (will execute sequentially)
+ */
+const resolveResourceConflicts = (actions) => {
+    // Check if there's a delete action
+    const hasDelete = actions.some(a => a.action === 'delete');
+
+    if (hasDelete) {
+        // Delete wins - drop all other actions and only keep the delete
+        return actions.filter(a => a.action === 'delete');
+    }
+
+    // No delete - return all actions (they'll execute sequentially)
+    return actions;
+};
+
+/**
+ * Executes actions for a single resource sequentially.
+ */
+const executeResourceActions = async (instanceUrl, token, actions) => {
+    const results = [];
+
+    for (const action of actions) {
+        try {
+            let result;
+            switch (action.action) {
+                case "create":
+                    result = await handleCreateAction(instanceUrl, token, action);
+                    break;
+                case "update":
+                    result = await handleUpdateAction(instanceUrl, token, action);
+                    break;
+                case "delete":
+                    result = await handleDeleteAction(instanceUrl, token, action);
+                    break;
+                default:
+                    throw new Error(`Unknown action: ${action.action}`);
+            }
+            results.push({ index: action.originalIndex, action, result, success: true });
+        } catch (error) {
+            results.push({ index: action.originalIndex, action, error: error.message, success: false });
+        }
+    }
+
+    return results;
+};
+
+/**
+ * Executes a single action and returns the result.
+ */
+const executeAction = async (instanceUrl, token, action) => {
+    let result;
+    switch (action.action) {
+        case "create":
+            result = await handleCreateAction(instanceUrl, token, action);
+            break;
+        case "update":
+            result = await handleUpdateAction(instanceUrl, token, action);
+            break;
+        case "delete":
+            result = await handleDeleteAction(instanceUrl, token, action);
+            break;
+        case "create_static_asset":
+            result = await handleCreateStaticAssetAction(instanceUrl, token, action);
+            break;
+        case "delete_static_asset":
+            result = await handleDeleteStaticAssetAction(instanceUrl, token, action);
+            break;
+        case "create_folder":
+            result = await handleCreateFolderAction(instanceUrl, token, action);
+            break;
+        case "delete_folder":
+            result = await handleDeleteFolderAction(instanceUrl, token, action);
+            break;
+        case "create_iris_app":
+        case "update_iris_app":
+            result = await handlePublishIrisAppAction(instanceUrl, token, action);
+            break;
+        case "delete_iris_app":
+            result = await handleDeleteIrisAppAction(instanceUrl, token, action);
+            break;
+        default:
+            throw new Error(`Unknown action: ${action.action}`);
+    }
+    return result;
+};
+
+/**
+ * Executes all actions sequentially (one at a time) with progress messages.
+ */
+const performNetworkRequestSequential = async (actionQueue) => {
+    const { instanceUrl, token } = await ensureValidCredentials();
+
+    console.log(chalk.blue(`\n🔄 Sequential processing mode (${actionQueue.length} operations)\n`));
+
+    const results = [];
+    let successCount = 0;
+    let errorCount = 0;
+
+    for (let i = 0; i < actionQueue.length; i++) {
+        const action = { ...actionQueue[i], originalIndex: i };
+        const displayName = getActionDisplayName(action);
+
+        // Show progress message
+        console.log(chalk.gray(`[${i + 1}/${actionQueue.length}] Processing ${action.action.toUpperCase()} ${displayName}...`));
+
+        try {
+            const result = await executeAction(instanceUrl, token.value, action);
+            results.push({ index: i, action, result, success: true });
+
+            successCount++;
+            console.log(
+                chalk.green(`✓ [${i + 1}]`) +
+                ` ${chalk.yellow(action.action.toUpperCase())} ${chalk.cyan(displayName)} ` +
+                (result?.recordId ? chalk.magenta(result.recordId) : "")
+            );
+            await updateCacheAfterSuccess(action, result);
+        } catch (error) {
+            results.push({ index: i, action, error: error.message, success: false });
+
+            errorCount++;
+            console.log();
+            console.log(chalk.bgRed.bold.white('  ✖ Operation Failed  '));
+            console.log(chalk.redBright('─'.repeat(48)));
+            const actionPath = action.filePath || action.folderPath || action.folder || action.appPath || action.slug || 'unknown';
+            console.log(chalk.red.bold(`[${i + 1}] ${action.action.toUpperCase()} ${displayName} (${actionPath}):`));
+            console.log(formatMultilineError(error.message));
+            console.log(chalk.redBright('─'.repeat(48)));
+        }
+
+        console.log(); // Add spacing between operations
+    }
+
+    // Summary
+    console.log(chalk.blue("--- Publish Summary ---"));
+    console.log(chalk.green(`✓ Successful: ${successCount}`));
+    if (errorCount > 0) {
+        console.log(chalk.red(`✗ Failed: ${errorCount}`));
+    } else {
+        console.log(chalk.green("All operations completed successfully! 🎉"));
+    }
+};
+
+/**
+ * Executes all actions in the queue with proper sequencing and conflict resolution (parallel mode).
+ */
+const performNetworkRequestParallel = async (actionQueue) => {
+    const { instanceUrl, token } = await ensureValidCredentials();
+
+    // Group actions by resource
+    const { byResource, assets } = groupActionsByResource(actionQueue);
+
+    // Resolve conflicts for each resource
+    const sequencedCodeActions = [];
+    const droppedActions = [];
+
+    for (const [resourceId, actions] of byResource.entries()) {
+        const resolved = resolveResourceConflicts(actions);
+        sequencedCodeActions.push(resolved);
+
+        // Track dropped actions
+        const droppedCount = actions.length - resolved.length;
+        if (droppedCount > 0) {
+            const dropped = actions.filter(a => !resolved.includes(a));
+            droppedActions.push(...dropped);
+        }
+    }
+
+    // Log dropped actions
+    if (droppedActions.length > 0) {
+        console.log(chalk.yellow(`\n⚠️  Dropped ${droppedActions.length} redundant operation(s) due to delete:`));
+        droppedActions.forEach(action => {
+            console.log(chalk.gray(`   • ${action.action.toUpperCase()} on ${getActionDisplayName(action)} (superseded by DELETE)`));
+        });
+    }
+
+    // Execute asset operations in parallel (they don't conflict)
+    const assetPromises = assets.map(async (action) => {
+        try {
+            const result = await executeAction(instanceUrl, token.value, action);
+            return { index: action.originalIndex, action, result, success: true };
+        } catch (error) {
+            return { index: action.originalIndex, action, error: error.message, success: false };
+        }
+    });
+
+    // Execute code entity operations sequentially per resource (but resources in parallel)
+    const codePromises = sequencedCodeActions.map(actions =>
+        executeResourceActions(instanceUrl, token.value, actions)
+    );
+
+    // Wait for all operations
+    const assetResults = await Promise.allSettled(assetPromises);
+    const codeResults = await Promise.allSettled(codePromises);
+
+    // Flatten code results
+    const allCodeResults = codeResults
+        .filter(r => r.status === 'fulfilled')
+        .flatMap(r => r.value);
+
+    const allAssetResults = assetResults
+        .map(r => r.status === 'fulfilled' ? r.value : { status: 'rejected', reason: r.reason });
+
+    // Combine all results
+    const allResults = [...allCodeResults, ...allAssetResults];
+
+    // Sort by original index to maintain order
+    allResults.sort((a, b) => (a.index || 0) - (b.index || 0));
+
+    // Process and display results
+    let successCount = 0;
+    let errorCount = 0;
+
+    for (const result of allResults) {
+        if (result.success !== undefined) {
+            const { index, action, success, error, result: operationResult } = result;
+
+            if (success) {
+                successCount++;
+                const displayName = getActionDisplayName(action);
+                console.log(
+                    chalk.green(`✓ [${index + 1}]`) +
+                    ` ${chalk.yellow(action.action.toUpperCase())} ${chalk.cyan(displayName)} ` +
+                    (operationResult?.recordId ? chalk.magenta(operationResult.recordId) : "")
+                );
+                await updateCacheAfterSuccess(action, operationResult);
+            } else {
+                errorCount++;
+                console.log();
+                console.log(chalk.bgRed.bold.white('  ✖ Operation Failed  '));
+                console.log(chalk.redBright('─'.repeat(48)));
+                const actionPath = action.filePath || action.folderPath || action.folder || action.appPath || action.slug || 'unknown';
+                console.log(chalk.red.bold(`[${index + 1}] ${action.action.toUpperCase()} ${getActionDisplayName(action)} (${actionPath}):`));
+                console.log(formatMultilineError(error));
+                console.log(chalk.redBright('─'.repeat(48)));
+            }
+        } else if (result.status === 'rejected') {
+            errorCount++;
+            console.log();
+            console.log(chalk.bgRed.bold.white('  ✖ Unexpected Error  '));
+            console.log(chalk.redBright('─'.repeat(48)));
+            console.log(`${chalk.redBright('  •')} ${chalk.whiteBright(result.reason)}`);
+            console.log(chalk.redBright('─'.repeat(48)));
+        }
+    }
+
+    // Summary
+    console.log(chalk.blue("\n--- Publish Summary ---"));
+    console.log(chalk.green(`✓ Successful: ${successCount}`));
+    if (droppedActions.length > 0) {
+        console.log(chalk.yellow(`⊝ Dropped: ${droppedActions.length} (redundant)`));
+    }
+    if (errorCount > 0) {
+        console.log(chalk.red(`✗ Failed: ${errorCount}`));
+    } else {
+        console.log(chalk.green("All operations completed successfully! 🎉"));
+    }
+};
+
+/**
+ * Executes all actions in the queue (dispatcher function).
+ */
+const performNetworkRequest = async (actionQueue) => {
+    if (USE_SEQUENTIAL_PROCESSING) {
+        return await performNetworkRequestSequential(actionQueue);
+    } else {
+        return await performNetworkRequestParallel(actionQueue);
+    }
+};
+
+/* ==================== MAIN PUBLISH LOGIC ==================== */
+
+/**
+ * Core publish logic - can be called from autopublish or directly.
+ * @param {Object} options - Configuration options
+ * @param {boolean} options.silent - If true, suppress summary output
+ * @returns {Promise<{actionQueue: Array, hasChanges: boolean}>}
+ */
+export const runPublish = async (options = {}) => {
+    const { silent = false } = options;
+
+    // Create progress tracker
+    const progress = silent ? null : new ProgressTracker('Publish to Magentrix');
+    if (progress) {
+        progress.addStep('auth', 'Authenticating...');
+        progress.addStep('load', 'Loading cached data...');
+        progress.addStep('scan', 'Scanning local files...');
+        progress.addStep('compare-assets', 'Comparing assets...', { hasProgress: true });
+        progress.addStep('compare-code', 'Comparing code entities...', { hasProgress: true });
+        progress.addStep('prepare', 'Preparing action queue...');
+        progress.start();
+        // Start first step immediately so UI shows up
+        progress.startStep('auth');
+    }
+
+    // Step 1: Authenticate
+    await ensureValidCredentials().catch((err) => {
+        if (progress) {
+            progress.abort(err.message);
+        } else if (!silent) {
+            console.error(chalk.red.bold("Authentication failed:"), chalk.white(err.message));
+        }
+        throw err;
+    });
+    if (progress) progress.completeStep('auth', '✓ Authenticated');
+
+    // Step 2: Load cached file state
+    if (progress) progress.startStep('load');
+
+    const loadStart = Date.now();
+    const hits = await config.searchObject({}, { filename: "base.json", global: false });
+    const cachedResults = hits?.[0]?.value || {};
+    const loadTime = Date.now() - loadStart;
+
+    if (!Object.keys(cachedResults).length) {
+        if (progress) {
+            progress.abort('No file cache found');
+        } else if (!silent) {
+            console.log(chalk.red.bold("No file cache found!"));
+            console.log(`Run ${chalk.cyan("magentrix pull")} to initialize your workspace.`);
+        }
+        throw new Error("No file cache found");
+    }
+
+    const mapStart = Date.now();
+    const cachedFiles = Object.values(cachedResults).map((c) => ({
+        ...c,
+        tag: c.recordId,
+        filePath: c.filePath || c.lastKnownPath,
+        type: c.type || c.Type,  // Normalize Type/type property
+    }));
+    const mapTime = Date.now() - mapStart;
+
+    if (progress) {
+        progress.completeStep('load', `✓ Loaded ${cachedFiles.length} entries (${loadTime}ms load, ${mapTime}ms map)`);
+    }
+
+    // Step 3: Scan local workspace (only whitelisted code entity directories)
+    if (progress) progress.startStep('scan');
+
+    const walkStart = Date.now();
+    // Only scan whitelisted directories for code entities (exclude Assets and iris-apps, handled separately)
+    const codeEntityDirs = ALLOWED_SRC_DIRS.filter(dir => dir !== 'Assets' && dir !== IRIS_APPS_DIR);
+    const localPathArrays = await Promise.all(
+        codeEntityDirs.map(dir => {
+            const dirPath = path.join(EXPORT_ROOT, dir);
+            return fs.existsSync(dirPath) ? walkFiles(dirPath) : Promise.resolve([]);
+        })
+    );
+    const localPaths = localPathArrays.flat();
+    const walkTime = Date.now() - walkStart;
+
+    const tagStart = Date.now();
+    const localFiles = await Promise.all(
+        localPaths.map(async (p) => {
+            try {
+                const tag = await getFileTag(p);
+                return { tag, path: p };
+            } catch {
+                return { tag: null, path: p };
+            }
+        })
+    );
+    const tagTime = Date.now() - tagStart;
+
+    if (progress) {
+        progress.completeStep('scan', `✓ Found ${localPaths.length} files (${walkTime}ms walk, ${tagTime}ms tags)`);
+    }
+
+    // Step 4: Create lookup maps
+    if (progress) progress.startStep('compare-assets');
+
+    const mapBuildStart = Date.now();
+    const cacheById = Object.fromEntries(cachedFiles.map((c) => [c.tag, c]));
+    const localById = Object.fromEntries(localFiles.filter((f) => f.tag).map((f) => [f.tag, f]));
+    const newLocalNoId = localFiles.filter((f) => !f.tag);
+    const allIds = new Set([...Object.keys(cacheById), ...Object.keys(localById)]);
+    const mapBuildTime = Date.now() - mapBuildStart;
+
+    const actionQueue = [];
+
+    // Step 5: Handle static asset files - Build fast lookup map first (O(n) instead of O(n²))
+    const assetWalkStart = Date.now();
+    const assetPaths = await walkFiles(path.join(EXPORT_ROOT, 'Assets'));
+    const assetWalkTime = Date.now() - assetWalkStart;
+
+    // Build a Set of normalized cached asset paths for O(1) lookup
+    const setStart = Date.now();
+    const cachedAssetPaths = new Set();
+    cachedFiles
+        .filter(cf => cf.type === 'File' || cf.type === 'Folder')
+        .forEach(cf => {
+            if (cf.lastKnownActualPath) {
+                cachedAssetPaths.add(path.normalize(path.resolve(cf.lastKnownActualPath)).toLowerCase());
+            }
+            if (cf.filePath) {
+                cachedAssetPaths.add(path.normalize(path.resolve(cf.filePath)).toLowerCase());
+            }
+            if (cf.lastKnownPath) {
+                cachedAssetPaths.add(path.normalize(path.resolve(cf.lastKnownPath)).toLowerCase());
+            }
+        });
+    const setTime = Date.now() - setStart;
+
+    // Now compare assets with O(1) lookup
+    for (let i = 0; i < assetPaths.length; i++) {
+        const assetPath = assetPaths[i];
+        const normalizedAssetPath = path.normalize(path.resolve(assetPath)).toLowerCase();
+
+        // Update progress every 100 files
+        if (progress && i % 100 === 0) {
+            progress.updateProgress('compare-assets', i, assetPaths.length, `Checking ${i}/${assetPaths.length} assets`);
+        }
+
+        // O(1) lookup instead of O(n) find()
+        if (cachedAssetPaths.has(normalizedAssetPath)) {
+            continue;
+        }
+
+        actionQueue.push({
+            action: "create_static_asset",
+            folder: toApiPath(assetPath),
+            filePath: assetPath
+        });
+    }
+
+    if (progress) {
+        progress.completeStep('compare-assets', `✓ Compared ${assetPaths.length} assets (walk:${assetWalkTime}ms, set:${setTime}ms, map:${mapBuildTime}ms)`);
+    }
+
+    // Step 6: Handle folder creation and deletion - Also optimized with Set
+    const assetsDir = path.join(EXPORT_ROOT, 'Assets');
+    if (fs.existsSync(assetsDir)) {
+        const localFolders = walkFolders(assetsDir);
+        const cachedFolders = cachedFiles
+            .filter(c => c.type === 'Folder' && (c.filePath || c.lastKnownPath || c.lastKnownActualPath));
+
+        // Build Set of cached folder paths for O(1) lookup
+        const cachedFolderPaths = new Set();
+        cachedFolders.forEach(cf => {
+            if (cf.lastKnownActualPath) {
+                cachedFolderPaths.add(path.normalize(path.resolve(cf.lastKnownActualPath)).toLowerCase());
+            }
+            if (cf.lastKnownPath) {
+                cachedFolderPaths.add(path.normalize(path.resolve(cf.lastKnownPath)).toLowerCase());
+            }
+            if (cf.filePath) {
+                cachedFolderPaths.add(path.normalize(path.resolve(cf.filePath)).toLowerCase());
+            }
+        });
+
+        // Build Set of local folder paths for O(1) lookup
+        const localFolderPaths = new Set(
+            localFolders.map(lf => path.normalize(path.resolve(lf)).toLowerCase())
+        );
+
+        // New folders - O(1) lookup
+        for (const folderPath of localFolders) {
+            if (!folderPath) continue;
+
+            const normalizedFolderPath = path.normalize(path.resolve(folderPath)).toLowerCase();
+
+            if (cachedFolderPaths.has(normalizedFolderPath)) {
+                continue;
+            }
+
+            const parentDir = path.dirname(folderPath);
+            if (!parentDir || parentDir === '.' || parentDir === folderPath) continue;
+
+            actionQueue.push({
+                action: "create_folder",
+                folderPath: folderPath,
+                parentPath: toApiFolderPath(parentDir),
+                folderName: path.basename(folderPath)
+            });
+        }
+
+        // Deleted folders - O(1) lookup
+        for (const cachedFolder of cachedFolders) {
+            const cachedPath = cachedFolder.lastKnownActualPath || cachedFolder.lastKnownPath || cachedFolder.filePath;
+            if (!cachedPath || typeof cachedPath !== 'string') continue;
+
+            const normalizedCachedPath = path.normalize(path.resolve(cachedPath)).toLowerCase();
+
+            if (localFolderPaths.has(normalizedCachedPath)) {
+                continue;
+            }
+
+            const parentDir = path.dirname(cachedPath);
+            if (!parentDir || parentDir === '.' || parentDir === cachedPath) continue;
+
+            actionQueue.push({
+                action: "delete_folder",
+                folderPath: cachedPath,
+                parentPath: toApiFolderPath(parentDir),
+                folderName: path.basename(cachedPath),
+                baseKey: cachedFolder.tag // The original base.json key for correct cache cleanup
+            });
+        }
+    }
+
+    // Step 7: Process code entities (ActiveClass/ActivePage) and static assets
+    if (progress) progress.startStep('compare-code');
+
+    const allIdsArray = Array.from(allIds);
+    for (let idx = 0; idx < allIdsArray.length; idx++) {
+        const id = allIdsArray[idx];
+
+        // Update progress every 50 items
+        if (progress && idx % 50 === 0) {
+            progress.updateProgress('compare-code', idx, allIdsArray.length, `Checking ${idx}/${allIdsArray.length} entities`);
+        }
+
+        try {
+            const cacheFile = cacheById[id];
+            const curFile = localById[id];
+
+            // Skip folders - they're handled separately
+            if (cacheFile?.type === 'Folder') continue;
+
+            // Skip Iris apps - they're handled separately (check both type and ID prefix)
+            if (cacheFile?.type === 'IrisApp' || id.startsWith('iris-app:')) continue;
+
+            // Handle static asset files
+            if (cacheFile?.type === 'File') {
+                // Use lastKnownActualPath which has the correct path (e.g., "src/Assets/...")
+                const actualPath = cacheFile.lastKnownActualPath || cacheFile.filePath;
+                const localAssetExists = fs.existsSync(actualPath);
+
+                if (!localAssetExists) {
+                    actionQueue.push({
+                        action: 'delete_static_asset',
+                        folder: toApiPath(actualPath),
+                        names: [path.basename(actualPath)],
+                        filePath: actualPath, // Store actual file path for filtering
+                        baseKey: id // The original base.json key for correct cache cleanup
+                    });
+                    continue;
+                }
+
+                const contentHash = sha256(fs.readFileSync(actualPath, 'utf-8'));
+                if (contentHash !== cacheFile.contentHash) {
+                    actionQueue.push({
+                        action: "create_static_asset",
+                        folder: toApiPath(actualPath),
+                        filePath: actualPath
+                    });
+                }
+                continue;
+            }
+
+            // Handle code entity deletion
+            if (cacheFile && !curFile) {
+                const { type, entity } = inferMeta(path.resolve(cacheFile.lastKnownPath));
+                actionQueue.push({
+                    action: "delete",
+                    recordId: id,
+                    filePath: cacheFile.lastKnownPath,
+                    type,
+                    entity,
+                });
+                continue;
+            }
+
+            // Handle code entity creation
+            if (!cacheFile && curFile) {
+                const safe = readFileSafe(curFile.path);
+                if (!safe) continue;
+
+                const { content, hash } = safe;
+                const { type, entity, contentField } = inferMeta(path.resolve(curFile.path));
+
+                actionQueue.push({
+                    action: "create",
+                    filePath: curFile.path,
+                    recordId: id || null,
+                    type,
+                    entity,
+                    fields: { [contentField]: content },
+                    contentHash: hash,
+                });
+                continue;
+            }
+
+            // Handle code entity update
+            if (cacheFile && curFile) {
+                const safe = readFileSafe(curFile.path);
+                if (!safe) continue;
+
+                const { content, hash } = safe;
+                // Check both paths - only consider renamed if NEITHER matches current path
+                // This prevents false positives from stale/corrupted tracking data
+                const resolvedCurPath = path.resolve(curFile.path);
+                const matchesActualPath = cacheFile.lastKnownActualPath === resolvedCurPath;
+                const matchesExpectedPath = cacheFile.lastKnownPath === resolvedCurPath;
+                const renamed = !matchesActualPath && !matchesExpectedPath;
+                const contentChanged = hash !== cacheFile.contentHash;
+
+                if (renamed || contentChanged) {
+                    const { type, entity, contentField } = inferMeta(path.resolve(curFile.path));
+
+                    actionQueue.push({
+                        action: "update",
+                        recordId: id,
+                        type,
+                        entity,
+                        fields: { [contentField]: content },
+                        renamed,
+                        oldPath: cacheFile.lastKnownActualPath || cacheFile.lastKnownPath,
+                        filePath: curFile.path,
+                    });
+                }
+            }
+        } catch (err) {
+            if (!silent) {
+                console.error(chalk.yellow(`Warning: Error processing file with ID ${id}:`), err.message);
+            }
+        }
+    }
+
+    if (progress) {
+        progress.completeStep('compare-code', `✓ Compared ${allIdsArray.length} code entities`);
+    }
+
+    // Step 7b: Scan and compare Iris apps
+    const irisAppsPath = path.join(EXPORT_ROOT, IRIS_APPS_DIR);
+
+    // Get cached Iris apps (always check, even if local folder doesn't exist)
+    // Also include entries with iris-app: prefix in case type wasn't properly set
+    const cachedIrisApps = cachedFiles
+        .filter(cf => cf.type === 'IrisApp' || (cf.tag && cf.tag.startsWith('iris-app:')))
+        .map(cf => {
+            // Extract slug from folderName, or from the ID (iris-app:<slug>)
+            const slug = cf.folderName || (cf.tag && cf.tag.startsWith('iris-app:') ? cf.tag.replace('iris-app:', '') : null);
+            return {
+                slug,
+                appName: cf.appName || slug,
+                modifiedOn: cf.modifiedOn,
+                contentHash: cf.contentHash || null  // Track content hash for change detection
+            };
+        })
+        .filter(app => app.slug); // Filter out any entries without a valid slug
+
+    // Get local Iris apps (empty if folder doesn't exist)
+    const localIrisApps = fs.existsSync(irisAppsPath)
+        ? fs.readdirSync(irisAppsPath, { withFileTypes: true })
+            .filter(d => d.isDirectory())
+            .map(d => d.name)
+        : [];
+
+    const cachedIrisSlugs = new Set(cachedIrisApps.map(a => a.slug));
+    const localIrisSlugs = new Set(localIrisApps);
+
+    // Detect new and modified Iris apps
+    for (const slug of localIrisApps) {
+        const appPath = path.join(irisAppsPath, slug);
+
+        // Validate the app folder has required files
+        const validation = validateIrisAppFolder(appPath);
+        if (!validation.valid) {
+            if (!silent) {
+                console.log(chalk.yellow(`⚠ Skipping invalid Iris app '${slug}': ${validation.errors.join(', ')}`));
+            }
+            continue;
+        }
+
+        // Get app metadata from linked project config (stored globally) or use slug
+        const linkedProjects = getLinkedProjects();
+        const linkedProject = linkedProjects.find(p => p.slug === slug);
+        const appName = linkedProject?.appName || slug;
+        const appDescription = linkedProject?.appDescription || null;
+        const appIconId = linkedProject?.appIconId || null;
+
+        // Calculate content hash for change detection
+        const currentHash = hashIrisAppFolder(appPath);
+
+        // Check if this is a new or existing app
+        const isNew = !cachedIrisSlugs.has(slug);
+
+        if (isNew) {
+            actionQueue.push({
+                action: 'create_iris_app',
+                slug,
+                appName,
+                appDescription,
+                appIconId,
+                appPath,
+                contentHash: currentHash
+            });
+        } else {
+            // Only update if content has changed
+            const cachedApp = cachedIrisApps.find(a => a.slug === slug);
+            const contentChanged = !cachedApp?.contentHash || cachedApp.contentHash !== currentHash;
+
+            if (contentChanged) {
+                actionQueue.push({
+                    action: 'update_iris_app',
+                    slug,
+                    appName: linkedProject?.appName || cachedApp?.appName || slug,
+                    appDescription,
+                    appIconId,
+                    appPath,
+                    contentHash: currentHash
+                });
+            }
+        }
+    }
+
+    // Detect deleted Iris apps (works even if iris-apps folder doesn't exist)
+    for (const cachedApp of cachedIrisApps) {
+        if (!localIrisSlugs.has(cachedApp.slug)) {
+            actionQueue.push({
+                action: 'delete_iris_app',
+                slug: cachedApp.slug
+            });
+        }
+    }
+
+    // Step 8: Handle brand-new, tag-less files
+    if (progress) progress.startStep('prepare');
+
+    for (const f of newLocalNoId) {
+        const safe = readFileSafe(f.path);
+        if (!safe) {
+            if (!silent) {
+                console.log(chalk.yellow(`Skipping unreadable file: ${f.path}`));
+            }
+            continue;
+        }
+
+        const { content, hash } = safe;
+        const { type, entity, contentField } = inferMeta(path.resolve(f.path));
+
+        actionQueue.push({
+            action: "create",
+            filePath: f.path,
+            recordId: null,
+            type,
+            entity,
+            fields: { [contentField]: content },
+            contentHash: hash,
+        });
+    }
+
+    // Step 9: Filter out redundant file and folder deletions
+    const foldersBeingDeleted = actionQueue
+        .filter(a => a.action === 'delete_folder')
+        .map(a => a.folderPath);
+
+    const filteredActionQueue = actionQueue.filter(action => {
+        // Filter out files inside folders being deleted
+        if (action.action === 'delete_static_asset' && action.filePath) {
+            const fileDir = path.dirname(action.filePath);
+            for (const deletedFolder of foldersBeingDeleted) {
+                const normalizedFileDir = path.normalize(fileDir);
+                const normalizedDeletedFolder = path.normalize(deletedFolder);
+
+                if (normalizedFileDir === normalizedDeletedFolder ||
+                    normalizedFileDir.startsWith(normalizedDeletedFolder + path.sep)) {
+                    return false; // Skip - covered by folder deletion
+                }
+            }
+        }
+
+        // Filter out child folders inside folders being deleted
+        if (action.action === 'delete_folder' && action.folderPath) {
+            for (const deletedFolder of foldersBeingDeleted) {
+                // Don't compare a folder to itself
+                if (action.folderPath === deletedFolder) continue;
+
+                const normalizedChildFolder = path.normalize(action.folderPath);
+                const normalizedParentFolder = path.normalize(deletedFolder);
+
+                // Check if this folder is inside another folder being deleted
+                if (normalizedChildFolder.startsWith(normalizedParentFolder + path.sep)) {
+                    return false; // Skip - covered by parent folder deletion
+                }
+            }
+        }
+
+        return true;
+    });
+
+    if (progress) {
+        progress.completeStep('prepare', `✓ Prepared ${filteredActionQueue.length} actions`);
+        progress.finish();
+    }
+
+    // Step 10: Display and execute action queue
+    if (!silent) {
+        console.log(chalk.blue("\n--- Publish Action Queue ---"));
+        if (!filteredActionQueue.length) {
+            console.log(chalk.green("All files are in sync — nothing to publish!"));
+        } else {
+            filteredActionQueue.forEach((a, i) => {
+                const num = chalk.green(`[${i + 1}]`);
+                const act = chalk.yellow(a.action.toUpperCase());
+
+                let type, displayPath, label;
+                if (a.slug) {
+                    // Iris app action
+                    type = chalk.cyan(`${a.appName || a.slug}`);
+                    displayPath = a.appPath || a.slug;
+                    label = "App";
+                } else if (a.folderName) {
+                    type = chalk.cyan(a.folderName);
+                    displayPath = a.folderPath;
+                    label = "Folder";
+                } else if (a.names) {
+                    type = chalk.cyan(a.names.join(", "));
+                    displayPath = a.folder;
+                    label = "File";
+                } else if (a.filePath) {
+                    type = chalk.cyan(a.type || path.basename(a.filePath));
+                    displayPath = a.filePath;
+                    label = a.type ? "Type" : "File";
+                } else {
+                    type = chalk.cyan(a.type || "Unknown");
+                    displayPath = a.folder || "Unknown";
+                    label = "File";
+                }
+
+                const idInfo = a.recordId ? ` ${chalk.magenta(a.recordId)}` : "";
+                const renameInfo = a.renamed
+                    ? ` → ${chalk.gray(a.oldPath)} ${chalk.white("→")} ${chalk.gray(a.filePath)}`
+                    : "";
+
+                console.log(`${num} ${act} | ${label}: ${type}${idInfo}${renameInfo} (${displayPath})`);
+            });
+
+            console.log(chalk.blue("\n--- Publishing Changes ---"));
+        }
+    }
+
+    // Execute actions
+    if (filteredActionQueue.length > 0) {
+        if (silent) {
+            await performNetworkRequest(filteredActionQueue);
+        } else {
+            await withSpinner(
+                "Working...",
+                async () => {
+                    await performNetworkRequest(filteredActionQueue)
+                },
+                { showCompletion: false }
+            );
+        }
+    }
+
+    return {
+        actionQueue: filteredActionQueue,
+        hasChanges: filteredActionQueue.length > 0
+    };
+};
+
+/**
+ * CLI command wrapper for publish.
+ */
+export const publish = async () => {
+    process.stdout.write("\x1Bc"); // clear console
+
+    try {
+        await runPublish({ silent: false });
+    } catch (err) {
+        console.error(chalk.red.bold("Publish failed:"), err.message);
+        process.exit(1);
+    }
+};