@magentrix-corp/magentrix-cli 1.3.13 → 1.3.14

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)
@@ -138,6 +141,8 @@ export const pull = async () => {
 
         // 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 = [];
@@ -188,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) => {
@@ -642,6 +648,8 @@ 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
@@ -663,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.13",
+  "version": "1.3.14",
   "description": "CLI tool for synchronizing local files with Magentrix cloud platform",
   "main": "index.js",
   "type": "module",

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/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/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);
     }