@magentrix-corp/magentrix-cli 1.3.12 → 1.3.14

package/actions/iris/buildStage.js

@@ -435,11 +435,23 @@ async function buildFromVueProject(options) {
     // This ensures pull doesn't overwrite our staged files
     console.log();
     console.log(chalk.gray('Checking workspace sync status...'));
+
+    // Check for a previous incomplete pull first — `magentrix status` only checks
+    // code entities, so a partial pull that synced code but not assets would falsely
+    // report "in sync". The marker file catches this case.
+    const workspaceConfig = new Config({ projectDir: workspacePath });
+    const hadIncompletePull = workspaceConfig.read('pullIncomplete', { global: false, filename: 'config.json' });
+
     const syncStatus = await checkWorkspaceSyncStatus(workspacePath);
+    const needsPull = syncStatus.needsPull || !!hadIncompletePull;
 
-    if (syncStatus.needsPull) {
+    if (needsPull) {
         console.log();
-        console.log(chalk.yellow('⚠ Your workspace may be out of sync with the server.'));
+        if (hadIncompletePull && !syncStatus.needsPull) {
+            console.log(chalk.yellow('⚠ A previous pull did not complete. Your workspace may be out of sync.'));
+        } else {
+            console.log(chalk.yellow('⚠ Your workspace may be out of sync with the server.'));
+        }
 
         const shouldPull = await confirm({
             message: 'Would you like to pull latest changes first?',
@@ -451,9 +463,16 @@ async function buildFromVueProject(options) {
             console.log(chalk.blue('Running pull from workspace...'));
             console.log();
 
+            // Mark pull as in-progress before starting
+            workspaceConfig.save('pullIncomplete', true, { global: false, filename: 'config.json' });
+
             const pullSuccess = await runCommandFromWorkspace(workspacePath, 'pull');
 
-            if (!pullSuccess) {
+            if (pullSuccess) {
+                // Pull completed successfully — clear the marker
+                workspaceConfig.removeKey('pullIncomplete', { filename: 'config.json' });
+            } else {
+                // Pull failed or was cancelled — marker stays for next run
                 console.log();
                 console.log(chalk.yellow('Pull encountered issues. You may want to resolve them manually.'));
 

package/actions/publish.js

@@ -199,9 +199,14 @@ const handleDeleteStaticAssetAction = async (instanceUrl, apiKey, action) => {
 
         if (isNotFound) {
             // Clean up base.json since file doesn't exist on server
-            for (const name of action.names) {
-                const filePath = action.filePath || `${EXPORT_ROOT}/${action.folder}/${name}`;
-                removeFromBase(filePath);
+            // 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 };
         }
@@ -253,7 +258,8 @@ const handleDeleteFolderAction = async (instanceUrl, apiKey, action) => {
 
         if (isNotFound) {
             // Clean up base.json since folder doesn't exist on server
-            removeFromBase(action.folderPath);
+            // 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 });
@@ -289,14 +295,19 @@ const handlePublishIrisAppAction = async (instanceUrl, apiKey, action) => {
     // Create zip from the app folder
     const zipBuffer = await createIrisZip(action.appPath, action.slug);
 
-    // Publish via API with app metadata
+    // 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`,
-        action.appName,
-        {
+        isUpdate ? null : action.appName,
+        isUpdate ? {} : {
             appDescription: action.appDescription,
             appIconId: action.appIconId
         }
@@ -425,9 +436,14 @@ const updateCacheAfterSuccess = async (action, operationResult) => {
             case "delete_static_asset":
                 // Skip if already cleaned from cache during 404 handling
                 if (!operationResult?.cleanedFromCache) {
-                    for (const name of action.names) {
-                        const filePath = action.filePath || `${EXPORT_ROOT}/${action.folder}/${name}`;
-                        removeFromBase(filePath);
+                    // 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;
@@ -443,8 +459,8 @@ const updateCacheAfterSuccess = async (action, operationResult) => {
             case "delete_folder": {
                 // Skip if already cleaned from cache during 404 handling
                 if (!operationResult?.cleanedFromCache) {
-                    // Remove the folder itself from base using recordId (which is the folderPath)
-                    removeFromBase(action.folderPath);
+                    // 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 });
@@ -1029,7 +1045,8 @@ export const runPublish = async (options = {}) => {
                 action: "delete_folder",
                 folderPath: cachedPath,
                 parentPath: toApiFolderPath(parentDir),
-                folderName: path.basename(cachedPath)
+                folderName: path.basename(cachedPath),
+                baseKey: cachedFolder.tag // The original base.json key for correct cache cleanup
             });
         }
     }
@@ -1067,7 +1084,8 @@ export const runPublish = async (options = {}) => {
                         action: 'delete_static_asset',
                         folder: toApiPath(actualPath),
                         names: [path.basename(actualPath)],
-                        filePath: actualPath // Store actual file path for filtering
+                        filePath: actualPath, // Store actual file path for filtering
+                        baseKey: id // The original base.json key for correct cache cleanup
                     });
                     continue;
                 }

package/actions/pull.js

@@ -1,4 +1,5 @@
 import { ensureValidCredentials } from "../utils/cli/helpers/ensureCredentials.js";
+import debug from '../utils/debug.js';
 import Config from "../utils/config.js";
 import { meqlQuery } from "../utils/magentrix/api/meqlQuery.js";
 import fs from "fs";
@@ -63,7 +64,9 @@ export const pull = async () => {
     try {
         // Step 1: Authenticate and retrieve instance URL and token
         progress.startStep('auth');
+        debug.log('PULL', 'Step 1: Authenticating...');
         const { instanceUrl, token } = await ensureValidCredentials();
+        debug.log('PULL', `Authenticated with instance: ${instanceUrl}`);
         progress.completeStep('auth', '✓ Authenticated');
 
         // Step 2: Check if instance URL has changed (credential switch detected)
@@ -128,13 +131,18 @@ export const pull = async () => {
         progress.startStep('load');
         const hits = await config.searchObject({}, { filename: "base.json", global: false });
         const cachedResults = hits?.[0]?.value || {};
-        const cachedAssets = Object.values(cachedResults).filter(c =>
-            c.type === 'File' || c.type === 'Folder'
-        );
+        // Include the base.json key (_baseKey) alongside each entry so we can
+        // use the correct key for removeFromBaseBulk later. The keys may differ
+        // from lastKnownActualPath/filePath due to path format inconsistencies.
+        const cachedAssets = Object.entries(cachedResults)
+            .filter(([, c]) => c.type === 'File' || c.type === 'Folder')
+            .map(([key, c]) => ({ ...c, _baseKey: key }));
         progress.completeStep('load', `✓ Loaded ${Object.keys(cachedResults).length} cached entries`);
 
         // Step 4a: Download code entities (ActiveClass and ActivePage)
         progress.startStep('download-code');
+        debug.log('PULL', 'Step 4a: Downloading code entities...');
+        debug.log('PULL', `Queries: ${queries.map(q => q.query).join(' | ')}`);
 
         let activeClassResult, activePageResult;
         const codeDownloadErrors = [];
@@ -185,6 +193,7 @@ export const pull = async () => {
         let assets;
         const assetDownloadErrors = [];
 
+        debug.log('PULL', 'Step 4b: Downloading static assets...');
         try {
             logger.info('Starting static asset downloads');
             assets = await downloadAssets(instanceUrl, token.value, null, (current, total, message) => {
@@ -338,7 +347,7 @@ export const pull = async () => {
 
                 // If this asset was in base.json but not returned from server, it was deleted
                 if (!serverAssetPaths.has(cachedPath)) {
-                    assetsToDelete.push(cachedPath);
+                    assetsToDelete.push({ path: cachedPath, baseKey: cached._baseKey });
                 }
 
                 processedCount++;
@@ -402,33 +411,35 @@ export const pull = async () => {
             // Delete local files/folders that were deleted on server
             logger.info(`Starting deletion of ${assetsToDelete.length} assets`);
             const deletionLogs = [];
-            for (const assetPath of assetsToDelete) {
+            // Track base.json keys for entries that need removal
+            const assetBaseKeysToRemove = [];
+            for (const asset of assetsToDelete) {
                 try {
-                    if (fs.existsSync(assetPath)) {
-                        const stats = fs.statSync(assetPath);
+                    if (fs.existsSync(asset.path)) {
+                        const stats = fs.statSync(asset.path);
                         if (stats.isDirectory()) {
-                            fs.rmSync(assetPath, { recursive: true, force: true });
-                            deletionLogs.push({ type: 'folder', path: assetPath });
-                            logger.info('Deleted folder', { path: assetPath });
+                            fs.rmSync(asset.path, { recursive: true, force: true });
+                            deletionLogs.push({ type: 'folder', path: asset.path });
+                            logger.info('Deleted folder', { path: asset.path });
                         } else {
-                            fs.unlinkSync(assetPath);
-                            deletionLogs.push({ type: 'file', path: assetPath });
-                            logger.info('Deleted file', { path: assetPath });
+                            fs.unlinkSync(asset.path);
+                            deletionLogs.push({ type: 'file', path: asset.path });
+                            logger.info('Deleted file', { path: asset.path });
                         }
                     }
+                    // Always remove from base.json regardless of whether the local file
+                    // existed — the server confirmed deletion, so the cache entry is stale.
+                    assetBaseKeysToRemove.push(asset.baseKey);
                 } catch (err) {
-                    deletionLogs.push({ type: 'error', path: assetPath, error: err.message });
-                    logger.error(`Failed to delete asset: ${assetPath}`, err);
+                    deletionLogs.push({ type: 'error', path: asset.path, error: err.message });
+                    logger.error(`Failed to delete asset: ${asset.path}`, err);
                 }
             }
 
-            // Bulk remove from base.json
-            const assetPathsToRemove = deletionLogs
-                .filter(l => l.type === 'file' || l.type === 'folder')
-                .map(l => l.path);
-
-            if (assetPathsToRemove.length > 0) {
-                removeFromBaseBulk(assetPathsToRemove);
+            // Bulk remove from base.json using the original base.json keys
+            // (not the normalized paths, which may have a different format)
+            if (assetBaseKeysToRemove.length > 0) {
+                removeFromBaseBulk(assetBaseKeysToRemove);
             }
 
             // Delete local code entity files that were deleted on server
@@ -637,8 +648,14 @@ export const pull = async () => {
         // Step 7: Finish progress tracker
         logger.info('Pull completed successfully');
         logger.close();
+        debug.log('PULL', 'Pull completed successfully');
+        debug.close();
         progress.finish('Pull completed successfully!');
 
+        // Clear any incomplete-pull marker (set by vue-run-build when a pull is
+        // started but cancelled/fails). A successful pull means we're fully synced.
+        config.removeKey('pullIncomplete', { filename: 'config.json' });
+
         // Summary
         console.log(chalk.bold(`Summary:`));
         console.log(`   • ${activeClassResult.Records.length} ActiveClass records`);
@@ -654,6 +671,8 @@ export const pull = async () => {
     } catch (error) {
         logger.error('Pull operation failed', error);
         logger.close();
+        debug.log('PULL', `Pull failed: ${error.message}`, error.stack);
+        debug.close();
         progress.abort(error.message);
 
         // Display log summary even on failure

package/bin/magentrix.js

@@ -21,9 +21,17 @@ import { irisLink, irisDev, irisDelete, irisRecover, vueBuildStage } from '../ac
 import Config from '../utils/config.js';
 import { registerWorkspace, getRegisteredWorkspaces } from '../utils/workspaces.js';
 import { ensureVSCodeFileAssociation } from '../utils/preferences.js';
+import debug from '../utils/debug.js';
 
 const config = new Config();
 
+// ── Debug Mode ───────────────────────────────
+// Check early (before Commander parses) so debug logging covers the full lifecycle
+if (process.argv.includes('--debug') || process.env.DEBUG === 'true') {
+    debug.enable();
+    debug.env();
+}
+
 // ── Vue Project Detection ────────────────────────────────
 /**
  * Check if current directory is a Vue project (has config.ts)
@@ -134,6 +142,7 @@ program
     .name('magentrix')
     .description('Manage Magentrix assets and automation')
     .version(VERSION)
+    .option('--debug', 'Enable debug logging')
     .configureHelp({
         formatHelp: (_cmd, _helper) => {
             const divider = chalk.gray('━'.repeat(60));
@@ -173,6 +182,7 @@ program
 
             help += `\n${chalk.bold.yellow('OPTIONS')}\n`;
             help += `  ${chalk.cyan('-V, --version')}  ${chalk.dim('Output the version number')}\n`;
+            help += `  ${chalk.cyan('--debug')}        ${chalk.dim('Enable debug logging to .magentrix/logs/')}\n`;
             help += `  ${chalk.cyan('-h, --help')}     ${chalk.dim('Display this help message')}\n`;
 
             help += `\n${chalk.bold.yellow('EXAMPLES')}\n`;
@@ -365,11 +375,15 @@ function handleFatal(err) {
     console.error(`\n${divider}\n${header}`);
     console.error(`${chalk.redBright(err?.message || 'An unexpected error occurred.')}\n`);
 
-    if (process.env.DEBUG === 'true' && err?.stack) {
-        console.error(chalk.dim(err.stack));
-        console.error();
+    if (debug.enabled) {
+        debug.log('FATAL', err?.message, err?.stack);
+        debug.close();
+        if (err?.stack) {
+            console.error(chalk.dim(err.stack));
+            console.error();
+        }
     } else {
-        console.log(`${chalk.yellow('💡  Run with')} ${chalk.cyan('DEBUG=true')} ${chalk.yellow('for full details.')}`);
+        console.log(`${chalk.yellow('💡  Run with')} ${chalk.cyan('--debug')} ${chalk.yellow('for full details.')}`);
     }
 
     console.log(divider + '\n');

package/package.json

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

package/utils/cacher.js

@@ -8,6 +8,9 @@ import { EXPORT_ROOT, ALLOWED_SRC_DIRS, IRIS_APPS_DIR } from '../vars/global.js'
 
 const config = new Config();
 
+// System/hidden files that should never be synced
+const IGNORED_FILES = new Set(['.DS_Store', 'Thumbs.db', 'desktop.ini']);
+
 /**
  * Recursively caches all files in a directory with tagging and content snapshotting
  * OPTIMIZED: Parallel processing + mtime checks for maximum speed
@@ -179,6 +182,11 @@ export async function walkFiles(dir, settings) {
     for (const entry of entries) {
         const fullPath = path.join(dir, entry.name);
 
+        // Skip OS-generated system files (.DS_Store, Thumbs.db, etc.)
+        if (IGNORED_FILES.has(entry.name)) {
+            continue;
+        }
+
         // Check if this path should be ignored
         if (ignore.find(p => fullPath.startsWith(p) || fullPath === p)) {
             continue;

package/utils/cli/helpers/ensureCredentials.js

@@ -2,6 +2,7 @@ import Config from "../../config.js";
 import { setup } from "../../../actions/setup.js";
 import { HASHED_CWD } from "../../../vars/global.js";
 import { tryAuthenticate } from "../../magentrix/api/auth.js";
+import debug from '../../debug.js';
 
 /**
  * Returns true if the token is present and not expired (60 seconds buffer).
@@ -31,16 +32,22 @@ export async function ensureValidCredentials() {
     const instanceUrl = config.read('instanceUrl', { global: true, pathHash: HASHED_CWD });
     const token = config.read('token', { global: true, pathHash: HASHED_CWD });
 
+    debug.auth(`Credential check: apiKey=${apiKey ? 'present' : 'missing'}, instanceUrl=${instanceUrl || '(missing)'}`);
+
     // If missing API key or URL, prompt/setup immediately
     if (!apiKey || !instanceUrl) {
+        debug.auth('Missing credentials, falling back to setup wizard');
         return setup();
     }
 
     // If token is present and valid, return immediately
     if (isTokenValid(token)) {
+        debug.auth(`Existing token is valid (expires: ${token.validUntil})`);
         return { apiKey, instanceUrl, token };
     }
 
+    debug.auth(`Token ${token ? `expired (was valid until: ${token.validUntil})` : 'missing'}, refreshing...`);
+
     // If we have API key & URL but no valid token, try to refresh
     try {
         const result = await tryAuthenticate(apiKey, instanceUrl);
@@ -54,6 +61,7 @@ export async function ensureValidCredentials() {
         config.save('token', newToken, { global: true, pathHash: HASHED_CWD });
         return { apiKey, instanceUrl, token: newToken };
     } catch (err) {
+        debug.auth(`Token refresh failed: ${err.message}, falling back to setup wizard`);
         // Failed to refresh, fall back to prompting the user
         return setup();
     }

package/utils/debug.js

@@ -0,0 +1,144 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { VERSION } from '../vars/config.js';
+import { CWD, HASHED_CWD } from '../vars/global.js';
+import Config from './config.js';
+
+/**
+ * Masks a sensitive string, showing only the first 4 and last 4 characters.
+ * @param {string} value
+ * @returns {string}
+ */
+function mask(value) {
+    if (!value || typeof value !== 'string') return '(empty)';
+    if (value.length <= 12) return '****';
+    return `${value.slice(0, 4)}...${value.slice(-4)}`;
+}
+
+/**
+ * Centralized debug logger singleton.
+ * When enabled, writes timestamped lines to .magentrix/logs/debug-<timestamp>.log.
+ * All methods are no-ops when debug.enabled === false.
+ */
+const debug = {
+    enabled: false,
+    _logFile: null,
+    _startTime: null,
+
+    /**
+     * Enable debug mode and open the log file.
+     */
+    enable() {
+        this.enabled = true;
+        this._startTime = Date.now();
+
+        const logsDir = path.join(CWD, '.magentrix', 'logs');
+        fs.mkdirSync(logsDir, { recursive: true, mode: 0o700 });
+
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        this._logFile = path.join(logsDir, `debug-${timestamp}.log`);
+
+        // Write header
+        fs.writeFileSync(this._logFile, `# MagentrixCLI Debug Log\n# Started: ${new Date().toISOString()}\n\n`, { mode: 0o600 });
+        console.log(`Debug log: ${path.relative(CWD, this._logFile)}`);
+    },
+
+    /**
+     * Write a timestamped line to the debug log.
+     * @param {string} label
+     * @param  {...any} args
+     */
+    log(label, ...args) {
+        if (!this.enabled || !this._logFile) return;
+        const elapsed = Date.now() - this._startTime;
+        const ts = `[+${String(elapsed).padStart(6)}ms]`;
+        const detail = args.length
+            ? ' ' + args.map(a => (typeof a === 'object' ? JSON.stringify(a, null, 2) : String(a))).join(' ')
+            : '';
+        fs.appendFileSync(this._logFile, `${ts} [${label}]${detail}\n`);
+    },
+
+    /**
+     * Log an outgoing HTTP request (sanitizes auth tokens/API keys).
+     */
+    request(method, url, headers, body) {
+        if (!this.enabled) return;
+        const safeHeaders = { ...headers };
+        if (safeHeaders.Authorization) {
+            safeHeaders.Authorization = `Bearer ${mask(safeHeaders.Authorization.replace('Bearer ', ''))}`;
+        }
+        this.log('HTTP-REQ', `${method} ${url}`);
+        this.log('HTTP-REQ', 'Headers:', JSON.stringify(safeHeaders, null, 2));
+        if (body !== undefined && body !== null) {
+            let bodyStr = typeof body === 'string' ? body : JSON.stringify(body, null, 2);
+            // Mask sensitive fields in body
+            bodyStr = bodyStr.replace(/"refresh_token"\s*:\s*"([^"]+)"/g, (_, val) => `"refresh_token": "${mask(val)}"`);
+            bodyStr = bodyStr.replace(/"apiKey"\s*:\s*"([^"]+)"/g, (_, val) => `"apiKey": "${mask(val)}"`);
+            this.log('HTTP-REQ', 'Body:', bodyStr);
+        }
+    },
+
+    /**
+     * Log an HTTP response including status, headers, and body.
+     */
+    response(status, statusText, headers, body) {
+        if (!this.enabled) return;
+        this.log('HTTP-RES', `${status} ${statusText}`);
+        if (headers) {
+            const headerObj = {};
+            if (typeof headers.forEach === 'function') {
+                headers.forEach((value, key) => { headerObj[key] = value; });
+            } else if (typeof headers === 'object') {
+                Object.assign(headerObj, headers);
+            }
+            this.log('HTTP-RES', 'Headers:', JSON.stringify(headerObj, null, 2));
+        }
+        if (body !== undefined && body !== null) {
+            let bodyStr = typeof body === 'string' ? body : JSON.stringify(body, null, 2);
+            // Mask tokens in response
+            bodyStr = bodyStr.replace(/"token"\s*:\s*"([^"]+)"/g, (_, val) => `"token": "${mask(val)}"`);
+            this.log('HTTP-RES', 'Body:', bodyStr);
+        }
+    },
+
+    /**
+     * Log environment information.
+     */
+    env() {
+        if (!this.enabled) return;
+        const config = new Config();
+        const instanceUrl = config.read('instanceUrl', { global: true, pathHash: HASHED_CWD }) || '(not set)';
+
+        this.log('ENV', 'Node version:', process.version);
+        this.log('ENV', 'OS:', `${os.type()} ${os.release()} (${os.arch()})`);
+        this.log('ENV', 'CLI version:', VERSION);
+        this.log('ENV', 'CWD:', CWD);
+        this.log('ENV', 'Hashed CWD:', HASHED_CWD);
+        this.log('ENV', 'Instance URL:', instanceUrl);
+    },
+
+    /**
+     * Auth-specific debug logging.
+     */
+    auth(message, details) {
+        if (!this.enabled) return;
+        if (details) {
+            this.log('AUTH', message, details);
+        } else {
+            this.log('AUTH', message);
+        }
+    },
+
+    /**
+     * Finalize the debug log and print its path.
+     */
+    close() {
+        if (!this.enabled || !this._logFile) return;
+        const elapsed = Date.now() - this._startTime;
+        this.log('END', `Debug session ended. Total time: ${elapsed}ms`);
+        console.log(`\nDebug log saved: ${path.relative(CWD, this._logFile)}`);
+    }
+};
+
+export default debug;

package/utils/iris/zipper.js

@@ -5,6 +5,9 @@ import { randomUUID, createHash } from 'node:crypto';
 import archiver from 'archiver';
 import extractZip from 'extract-zip';
 
+// System/hidden files that should never be included in IRIS app zips or hashes
+const IGNORED_FILES = new Set(['.DS_Store', 'Thumbs.db', 'desktop.ini']);
+
 /**
  * Recursively fix permissions on extracted files.
  * Sets directories to 0o755 and files to 0o644.
@@ -61,7 +64,10 @@ export async function createIrisZip(distPath, appSlug) {
 
         // Add the dist directory contents under the app slug folder
         // This creates the structure: appSlug/remoteEntry.js, appSlug/assets/...
-        archive.directory(distPath, appSlug);
+        // Filter out OS-generated system files (.DS_Store, Thumbs.db, etc.)
+        archive.directory(distPath, appSlug, (entry) =>
+            IGNORED_FILES.has(basename(entry.name)) ? false : entry
+        );
 
         archive.finalize();
     });
@@ -195,6 +201,9 @@ export function getFilesRecursive(dir, basePath = dir) {
     function walk(currentDir) {
         const entries = readdirSync(currentDir);
         for (const entry of entries) {
+            // Skip OS-generated system files
+            if (IGNORED_FILES.has(entry)) continue;
+
             const fullPath = join(currentDir, entry);
             const stat = statSync(fullPath);
             if (stat.isDirectory()) {

package/utils/magentrix/api/auth.js

@@ -1,5 +1,6 @@
 import { fetchMagentrix } from "../fetch.js";
 import chalk from "chalk";
+import debug from '../../debug.js';
 
 /**
  * Authenticates with Magentrix and retrieves an access token using the API key as a refresh token.
@@ -11,6 +12,7 @@ import chalk from "chalk";
  * @returns {Promise<string>} Resolves to the Magentrix access token string.
  */
 export const getAccessToken = async (apiKey, instanceUrl) => {
+    debug.auth(`Requesting access token from ${instanceUrl}/api/3.0/token`);
     try {
         const data = await fetchMagentrix({
             instanceUrl,
@@ -22,12 +24,14 @@ export const getAccessToken = async (apiKey, instanceUrl) => {
             method: "POST"
         })
 
+        debug.auth('Token received successfully', { validUntil: data.validUntil });
         // Success
         return {
             token: data.token,
             validUntil: data.validUntil
         };
     } catch (error) {
+        debug.auth(`Token request failed: ${error.message}`);
         throw new Error(`Error retrieving Magentrix access token: ${error.message}`);
     }
 };
@@ -52,35 +56,43 @@ export const tryAuthenticate = async (apiKey, instanceUrl) => {
         let formattedMessage = '\n' + chalk.red.bold('✖ Authentication Failed') + '\n';
         formattedMessage += chalk.dim('─'.repeat(50)) + '\n\n';
 
+        debug.auth(`Authentication failed, categorizing error: ${errorMessage.substring(0, 100)}`);
+
         if (errorMessage.includes('Network error')) {
+            debug.auth('Error category: Network error (unable to reach instance)');
             formattedMessage += chalk.cyan.bold('🌐 Unable to reach the Magentrix instance') + '\n\n';
             formattedMessage += chalk.yellow('  Possible causes:') + '\n';
             formattedMessage += chalk.gray('  • Check your internet connection') + '\n';
             formattedMessage += chalk.gray('  • Verify the instance URL is correct') + '\n';
             formattedMessage += chalk.gray('  • Ensure the server is online and accessible') + '\n';
         } else if (errorMessage.includes('HTTP 401') || errorMessage.includes('HTTP 403') || errorMessage.includes('Unauthorized')) {
+            debug.auth('Error category: Invalid API key (401/403)');
             formattedMessage += chalk.cyan.bold('🔑 Invalid API Key') + '\n\n';
             formattedMessage += chalk.yellow('  What to do:') + '\n';
             formattedMessage += chalk.gray('  • The API key you entered is incorrect') + '\n';
             formattedMessage += chalk.gray('  • Verify your API key from the Magentrix admin panel') + '\n';
         } else if (errorMessage.includes('HTTP 404')) {
+            debug.auth('Error category: Invalid instance URL (404)');
             formattedMessage += chalk.cyan.bold('🔍 Invalid Magentrix Instance URL') + '\n\n';
             formattedMessage += chalk.yellow('  What to do:') + '\n';
             formattedMessage += chalk.gray('  • The URL does not appear to be a valid Magentrix server') + '\n';
             formattedMessage += chalk.gray('  • Verify the URL matches your Magentrix instance') + '\n';
         } else if (errorMessage.includes('HTTP 5')) {
+            debug.auth('Error category: Server error (5xx)');
             formattedMessage += chalk.cyan.bold('⚠️  Magentrix Server Error') + '\n\n';
             formattedMessage += chalk.yellow('  What to do:') + '\n';
             formattedMessage += chalk.gray('  • The server is experiencing issues') + '\n';
             formattedMessage += chalk.gray('  • Please try again in a few moments') + '\n';
             formattedMessage += chalk.gray('  • Contact support if the issue persists') + '\n';
         } else if (errorMessage.includes('timeout') || errorMessage.includes('ETIMEDOUT')) {
+            debug.auth('Error category: Connection timeout');
             formattedMessage += chalk.cyan.bold('⏱️  Connection Timeout') + '\n\n';
             formattedMessage += chalk.yellow('  What to do:') + '\n';
             formattedMessage += chalk.gray('  • The server took too long to respond') + '\n';
             formattedMessage += chalk.gray('  • Check your internet connection') + '\n';
             formattedMessage += chalk.gray('  • Try again in a moment') + '\n';
         } else {
+            debug.auth('Error category: Unknown error');
             formattedMessage += chalk.cyan.bold('❓ Unable to Authenticate') + '\n\n';
             formattedMessage += chalk.yellow('  What to do:') + '\n';
             formattedMessage += chalk.gray('  • Verify both your API key and instance URL are correct') + '\n';

package/utils/magentrix/api/iris.js

@@ -48,10 +48,6 @@ export const publishApp = async (instanceUrl, token, zipBuffer, filename, appNam
         throw new Error('filename is required');
     }
 
-    if (!appName) {
-        throw new Error('appName is required for navigation menu updates');
-    }
-
     // Create a File object from the buffer for FormData
     const file = new File([zipBuffer], filename, { type: 'application/zip' });
 
@@ -59,8 +55,14 @@ export const publishApp = async (instanceUrl, token, zipBuffer, filename, appNam
     formData.append('file', file);
 
     // Build query parameters
+    // Note: app-name is only sent when provided (required for creates, optional for updates)
+    // Sending app-name on updates can trigger a rename attempt that fails if the user
+    // lacks metadata-edit permissions on the server
     const params = new URLSearchParams();
-    params.append('app-name', appName);
+
+    if (appName) {
+        params.append('app-name', appName);
+    }
 
     if (options.appDescription) {
         params.append('app-description', options.appDescription);

package/utils/magentrix/api/meqlQuery.js

@@ -1,4 +1,5 @@
 import { fetchMagentrix } from "../fetch.js";
+import debug from '../../debug.js';
 
 /**
  * Executes a Magentrix Entity Query Language (MEQL) query via the REST API v3.
@@ -18,6 +19,8 @@ export const meqlQuery = async (instanceUrl, token, query = '') => {
         throw new Error('MEQL query string is required');
     }
 
+    debug.log('MEQL', `Query: ${query}`);
+
     const data = await fetchMagentrix({
         instanceUrl,
         token,
@@ -26,6 +29,8 @@ export const meqlQuery = async (instanceUrl, token, query = '') => {
         body: query
     })
 
+    debug.log('MEQL', `Result: ${data?.Records?.length ?? 0} records returned`);
+
     // --- Success ---
     return data;
 };

package/utils/magentrix/fetch.js

@@ -1,3 +1,5 @@
+import debug from '../debug.js';
+
 /**
  * Checks if a request body should be JSON-stringified.
  * Excludes FormData, Blob, ArrayBuffer, URLSearchParams, and typed arrays.
@@ -71,14 +73,18 @@ export const fetchMagentrix = async ({
     }
     if (!finalHeaders['Content-Type'] && !ignoreContentType) finalHeaders['Content-Type'] = 'application/json';
 
+    const fullUrl = `${instanceUrl.replace(/\/$/, '')}${path}`;
+    debug.request(method, fullUrl, finalHeaders, body);
+
     let response, responseData;
     try {
-        response = await fetch(`${instanceUrl.replace(/\/$/, '')}${path}`, {
+        response = await fetch(fullUrl, {
             method,
             headers: finalHeaders,
             body: requestBody
         });
     } catch (err) {
+        debug.log('HTTP-ERR', `Network error: ${err.message}`, err.stack);
         const errorObj = {
             type: 'network',
             message: `Network error contacting Magentrix API: ${err.message}`,
@@ -94,6 +100,8 @@ export const fetchMagentrix = async ({
         responseData = null;
     }
 
+    debug.response(response.status, response.statusText, response.headers, responseData);
+
     if (!response.ok) {
         const errorObj = {
             type: 'http',
@@ -117,6 +125,7 @@ export const fetchMagentrix = async ({
         }
         if (errorConfig?.includeURL) msg += `\nURL: ${response.url}`;
         errorObj.message = msg;
+        debug.log('HTTP-ERR', `HTTP ${response.status}: ${msg}`);
         if (returnErrorObject) throw errorObj;
         throw new Error(msg);
     }
@@ -146,6 +155,7 @@ export const fetchMagentrix = async ({
             details = String(responseData);
         }
         errorObj.message = `Magentrix API error:\n${details}`;
+        debug.log('API-ERR', errorObj.message);
         if (returnErrorObject) throw errorObj;
         throw new Error(errorObj.message);
     }