@magentrix-corp/magentrix-cli 1.1.4 → 1.2.0

package/README.md

@@ -24,7 +24,7 @@ Before you start, make sure you have:
    - Verify installation: `node --version`
 
 2. **Access to a Magentrix instance**
-   - You need the URL (e.g., `https://yourcompany.magentrixcloud.com`)
+   - You need the URL (e.g., `https://yourcompany.magentrix.com`)
 
 3. **API Key from Magentrix**
    - Get this from your Magentrix administrator or system settings
@@ -111,6 +111,57 @@ Your configuration and local files are preserved during updates. You don't need
 
 ---
 
+## Multi-Instance Setup
+
+### Working with Multiple Magentrix Instances
+
+MagentrixCLI supports managing multiple Magentrix instances simultaneously by storing credentials per-folder. This means you can have different folders for different instances, and the CLI will automatically use the correct credentials based on which folder you're in.
+
+#### How It Works
+
+The CLI uses a folder hash to associate credentials with each project directory. When you run `magentrix setup` in a folder, the API key and instance URL are stored globally but linked to that specific folder location.
+
+#### Setting Up Multiple Instances
+
+**Example**: Managing both Production and Development instances
+
+```bash
+# Set up Production instance
+mkdir ~/magentrix-production
+cd ~/magentrix-production
+magentrix setup
+# Enter production API key and URL
+magentrix pull
+
+# Set up Development instance
+mkdir ~/magentrix-development
+cd ~/magentrix-development
+magentrix setup
+# Enter development API key and URL
+magentrix pull
+```
+
+Now you can work on both instances independently:
+
+```bash
+# Work on production
+cd ~/magentrix-production
+magentrix publish    # Publishes to production instance
+
+# Work on development
+cd ~/magentrix-development
+magentrix publish    # Publishes to development instance
+```
+
+#### Important Notes
+
+- Each folder maintains its own independent configuration
+- Credentials are stored securely in your system's config directory
+- Moving or renaming project folders will require running `magentrix setup` again
+- You can verify which instance you're connected to by running `magentrix` or `magentrix config`
+
+---
+
 ## First Time Setup
 
 ### Step 1: Configure Your Credentials
@@ -124,13 +175,13 @@ magentrix setup
 
 You'll be prompted for:
 - **API Key**: Paste your Magentrix API key
-- **Instance URL**: Enter your Magentrix URL (like `https://yourcompany.magentrixcloud.com`)
+- **Instance URL**: Enter your Magentrix instance URL (like `https://yourcompany.magentrix.com` or any custom domain)
 
 #### Non-Interactive Setup
 For automation or CI/CD, you can provide credentials via command-line flags:
 
 ```bash
-magentrix setup --api-key YOUR_API_KEY --instance-url https://yourcompany.magentrixcloud.com
+magentrix setup --api-key YOUR_API_KEY --instance-url https://yourcompany.magentrix.com
 ```
 
 **Available flags:**
@@ -170,16 +221,31 @@ magentrix
 **What it does**: Displays your current connection status, API key (masked), and Magentrix instance URL.
 **When to use**: Quick check to verify you're properly authenticated and connected to the right instance.
 
+### Configure CLI Settings
+```bash
+magentrix config
+```
+**What it does**: Opens an interactive configuration wizard where you can manage CLI settings such as:
+- **Log File Settings**: Enable or disable detailed operation logs
+- **View All Settings**: See your current configuration including API key (masked) and instance URL
+
+**When to use**:
+- To enable or disable operation logs for debugging
+- To verify your current settings and credentials
+- To manage CLI preferences without re-running setup
+
 ### Download Latest Files from Server
 ```bash
 magentrix pull
 ```
-**What it does**: Downloads all ActiveClass and ActivePage records from your Magentrix server to your local `src/` folder. Detects conflicts if files have been changed both locally and remotely, and prompts you to resolve them.
+**What it does**: Downloads all ActiveClass and ActivePage records from your Magentrix server to your local `src/` folder. Detects conflicts if files have been changed both locally and remotely, and prompts you to resolve them. Progress tracking shows separate steps for code entities and static assets.
 **When to use**:
 - Start of your workday to get latest changes
 - Before making major changes to avoid conflicts
 - When teammates have made server changes you need
 
+**Note**: If this is your first time running `magentrix pull` in a project with many files, you may be prompted about saving operation logs. This is a one-time setup that helps with debugging.
+
 ### Check Status and Conflicts
 ```bash
 magentrix status
@@ -194,12 +260,14 @@ magentrix status
 ```bash
 magentrix publish
 ```
-**What it does**: Sends all unpublished changes from your local machine to the Magentrix server and compiles them. Shows you exactly what will be created, updated, or deleted before doing it. Processes all changes in parallel for speed. Works with both code files and static assets.
+**What it does**: Sends all unpublished changes from your local machine to the Magentrix server and compiles them. Shows you exactly what will be created, updated, or deleted before doing it. Processes all changes in parallel for speed. Works with both code files and static assets. Features comprehensive progress tracking with timing diagnostics for large projects.
 **When to use**:
 - After you've finished making changes and want to deploy them
 - At the end of your work session
 - When you want to share your changes with teammates
 
+**Performance Note**: The CLI uses optimized algorithms for large projects. Even with 20,000+ files, initial scanning completes in under 2 seconds.
+
 ### Real-Time Development Mode
 ```bash
 magentrix autopublish
@@ -528,6 +596,72 @@ This separation gives you the best of both worlds - robust version control AND s
 
 ---
 
+## Operation Logs
+
+### About Logs
+
+MagentrixCLI can save detailed operation logs to help with debugging and troubleshooting. This is particularly useful when dealing with large projects or investigating sync issues.
+
+### Enabling/Disabling Logs
+
+#### First Time Prompt
+The first time you run an operation like `magentrix pull` or `magentrix publish`, you'll be asked:
+
+```
+📋 Log File Settings
+Magentrix CLI can save detailed operation logs for debugging.
+
+? Would you like to save operation logs to files? (Y/n)
+```
+
+Your choice is saved globally and applies to all future operations.
+
+#### Change Settings Later
+You can change your logging preference at any time:
+
+```bash
+magentrix config
+```
+
+Then select "Log File Settings" from the menu to enable or disable logs.
+
+### Log File Location
+
+When enabled, logs are saved to `.magentrix/logs/` in your project folder:
+
+```
+.magentrix/
+└── logs/
+    ├── pull-2025-01-15T14-30-45.log
+    ├── publish-2025-01-15T15-12-30.log
+    └── autopublish-2025-01-15T16-00-00.log
+```
+
+### What Gets Logged
+
+Operation logs include:
+- Detailed timestamps for each operation
+- Warnings about unknown file types or edge cases
+- Errors with full stack traces
+- Information about files being processed
+- API calls and responses
+
+### Viewing Logs
+
+To view a log file:
+
+```bash
+cat .magentrix/logs/pull-2025-01-15T14-30-45.log
+```
+
+Or open it in your text editor.
+
+### Log Cleanup
+
+The CLI automatically keeps only the 10 most recent log files per operation type to prevent disk space issues. Older logs are automatically deleted.
+
+---
+
 ## Troubleshooting
 
 ### "Authentication failed"
@@ -553,6 +687,12 @@ This separation gives you the best of both worlds - robust version control AND s
 - Run `magentrix publish` to upload any remaining changes
 - Restart with `magentrix autopublish`
 
+### Need More Debugging Information
+- Enable operation logs via `magentrix config`
+- Run the failing operation again
+- Check `.magentrix/logs/` for detailed error information
+- Share log files with your team or support for help
+
 ---
 
 ## Tips & Best Practices
@@ -583,13 +723,19 @@ The tool creates these configuration files (you normally don't need to edit them
 
 ### Global Settings
 - **Location**: `~/.config/magentrix/` (Mac/Linux) or `%APPDATA%/magentrix/` (Windows)
-- **Contains**: Your API credentials and connection settings
+- **Contains**:
+  - API credentials and connection settings (namespaced by folder hash)
+  - Global preferences like log settings
+  - Multiple instance credentials (each folder has its own credentials)
 
 ### Project Settings
 - **Location**: `.magentrix/` folder in your project
-- **Contains**: File mappings, sync status, and local cache
+- **Contains**:
+  - File mappings and sync status
+  - Local cache and operation logs (if enabled)
+  - Base file snapshots for conflict detection
 
-**Note**: These folders are created automatically. Don't delete them unless you want to reconfigure everything.
+**Note**: These folders are created automatically. Don't delete them unless you want to reconfigure everything. The global config supports multiple instances by storing credentials per-project folder.
 
 ---
 
@@ -609,11 +755,13 @@ magentrix status        # Shows sync status
 
 ### Common Commands Summary
 - `magentrix setup` - Configure credentials
+- `magentrix config` - Manage CLI settings
 - `magentrix pull` - Download files from server
 - `magentrix publish` - Upload local changes
 - `magentrix create` - Create new files
 - `magentrix status` - Check sync status
 - `magentrix autopublish` - Auto-sync mode
+- `magentrix update` - Update to latest version
 
 ---
 

package/actions/config.js

@@ -0,0 +1,182 @@
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import Config from '../utils/config.js';
+import { HASHED_CWD } from '../vars/global.js';
+
+const config = new Config();
+
+/**
+ * Interactive configuration wizard
+ */
+export const configWizard = async () => {
+    console.clear();
+    console.log(chalk.cyan.bold('\n⚙️  Magentrix CLI Configuration'));
+    console.log(chalk.gray('─'.repeat(50)));
+    console.log('');
+
+    while (true) {
+        const { action } = await inquirer.prompt([
+            {
+                type: 'list',
+                name: 'action',
+                message: 'What would you like to do?',
+                pageSize: 10,
+                loop: false,
+                choices: [
+                    {
+                        name: '  📋  Log File Settings',
+                        value: 'logs',
+                        short: 'Log Settings'
+                    },
+                    {
+                        name: '  🔧  View All Settings',
+                        value: 'view',
+                        short: 'View Settings'
+                    },
+                    new inquirer.Separator(),
+                    {
+                        name: chalk.gray('  Exit'),
+                        value: 'exit',
+                        short: 'Exit'
+                    }
+                ]
+            }
+        ]);
+
+        if (action === 'exit') {
+            console.log('');
+            console.log(chalk.green('✓ Configuration saved'));
+            console.log('');
+            break;
+        }
+
+        console.clear();
+        console.log(chalk.cyan.bold('\n⚙️  Magentrix CLI Configuration'));
+        console.log(chalk.gray('─'.repeat(50)));
+
+        switch (action) {
+            case 'logs':
+                await configureLogSettings();
+                break;
+            case 'view':
+                await viewAllSettings();
+                break;
+        }
+
+        console.clear();
+        console.log(chalk.cyan.bold('\n⚙️  Magentrix CLI Configuration'));
+        console.log(chalk.gray('─'.repeat(50)));
+        console.log('');
+    }
+};
+
+/**
+ * Configure log file settings
+ */
+async function configureLogSettings() {
+    const currentSetting = config.read('saveLogs', { global: true });
+
+    console.log('');
+    console.log(chalk.cyan.bold('📋  Log File Settings'));
+    console.log(chalk.gray('Detailed operation logs can be saved to .magentrix/logs/ for debugging.'));
+    console.log('');
+
+    // Show current status with better formatting
+    const currentStatus = currentSetting === true || currentSetting === 'true'
+        ? chalk.green('● ENABLED') + chalk.gray(' - Logs are being saved')
+        : currentSetting === false || currentSetting === 'false'
+            ? chalk.yellow('○ DISABLED') + chalk.gray(' - No log files created')
+            : chalk.gray('○ Not set') + chalk.gray(' - Will prompt on first use');
+
+    console.log(chalk.bold('Current Status: ') + currentStatus);
+    console.log('');
+
+    const { setting } = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'setting',
+            message: 'Choose preference:',
+            pageSize: 10,
+            loop: false,
+            choices: [
+                {
+                    name: '  ' + chalk.green('● Enable logs'),
+                    value: true,
+                    short: 'Enable'
+                },
+                {
+                    name: '  ' + chalk.yellow('○ Disable logs'),
+                    value: false,
+                    short: 'Disable'
+                },
+                new inquirer.Separator(),
+                {
+                    name: chalk.gray('  ← Back'),
+                    value: 'back',
+                    short: 'Back'
+                }
+            ],
+            default: currentSetting === true || currentSetting === 'true' ? 0 : (currentSetting === false || currentSetting === 'false' ? 1 : 0)
+        }
+    ]);
+
+    if (setting === 'back') return;
+
+    config.save('saveLogs', setting, { global: true });
+
+    console.log('');
+    if (setting) {
+        console.log(chalk.green('✓ Logs enabled'));
+        console.log(chalk.gray('  → Logs will be saved to .magentrix/logs/'));
+    } else {
+        console.log(chalk.yellow('✓ Logs disabled'));
+        console.log(chalk.gray('  → No log files will be created'));
+    }
+
+    console.log('');
+    console.log(chalk.gray('Press Enter to continue...'));
+    await inquirer.prompt([{ type: 'input', name: 'continue', message: '' }]);
+}
+
+/**
+ * View all current settings
+ */
+async function viewAllSettings() {
+    console.log('');
+    console.log(chalk.cyan.bold('🔧  All Settings'));
+    console.log('');
+
+    // Log settings
+    const saveLogs = config.read('saveLogs', { global: true });
+    const logsStatus = saveLogs === true || saveLogs === 'true'
+        ? chalk.green('● Enabled')
+        : saveLogs === false || saveLogs === 'false'
+            ? chalk.yellow('○ Disabled')
+            : chalk.gray('○ Not set');
+    console.log(chalk.bold('  Log Files'));
+    console.log(`  ${logsStatus}`);
+    console.log('');
+
+    // API Key (masked) - read with pathHash like setup command does
+    const apiKey = config.read('apiKey', { global: true, pathHash: HASHED_CWD });
+    const keyStatus = apiKey
+        ? chalk.green('****' + String(apiKey).slice(-4))
+        : chalk.gray('Not configured');
+    console.log(chalk.bold('  API Key'));
+    console.log(`  ${keyStatus}`);
+    console.log('');
+
+    // Instance URL - read with pathHash like setup command does
+    const instanceUrl = config.read('instanceUrl', { global: true, pathHash: HASHED_CWD });
+    const urlStatus = instanceUrl
+        ? chalk.cyan(instanceUrl)
+        : chalk.gray('Not configured');
+    console.log(chalk.bold('  Instance URL'));
+    console.log(`  ${urlStatus}`);
+    console.log('');
+
+    console.log(chalk.gray('─'.repeat(50)));
+    console.log('');
+    console.log(chalk.gray('Press Enter to continue...'));
+    await inquirer.prompt([{ type: 'input', name: 'continue', message: '' }]);
+}

package/actions/create.js

@@ -400,14 +400,27 @@ export const create = async (cliOptions = {}) => {
     console.log();
 
     // Uncomment to perform creation via API:
-    const creationResponse = await withSpinner('Creating file...', async () => {        
+    const creationResponse = await withSpinner('Creating file...', async () => {
         return await createEntity(
-            credentials.instanceUrl, 
-            credentials.token.value, 
-            entityType, 
+            credentials.instanceUrl,
+            credentials.token.value,
+            entityType,
             formattedData
         ).catch(err => {
-            return { ...err?.response, hasErrors: true };
+            // The error object structure from fetchMagentrix:
+            // - err.type: 'network' | 'http' | 'api'
+            // - err.message: formatted error message
+            // - err.response: the API response data (if available)
+            // - err.status: HTTP status code (for http errors)
+            return {
+                hasErrors: true,
+                errorType: err.type,
+                errorMessage: err.message,
+                status: err.status,
+                statusText: err.statusText,
+                errors: err.response?.errors || err.response?.Errors || [],
+                rawResponse: err.response
+            };
         });
     });
 
@@ -415,17 +428,25 @@ export const create = async (cliOptions = {}) => {
         console.log();
         console.log(chalk.bgRed.bold.white('  ✖ Creation Failed  '));
         console.log(chalk.redBright('─'.repeat(48)));
+
+        // Display HTTP status if available
+        if (creationResponse.status) {
+            console.log(chalk.yellow(`  Status: ${creationResponse.status} ${creationResponse.statusText || ''}`));
+        }
+
         const errors = creationResponse.errors || [];
 
         if (errors.length > 0) {
             errors.forEach((err) => {
                 const code = err.code ? chalk.gray(`[${err.code}] `) : '';
-                const status = err.status ? chalk.yellow(`[${err.status}] `) : '';
-                const msg = chalk.whiteBright(err.message);
-                console.log(`${chalk.redBright('  •')} ${status}${code}${msg}`);
+                const msg = chalk.whiteBright(err.message || err);
+                console.log(`${chalk.redBright('  •')} ${code}${msg}`);
             });
+        } else if (creationResponse.errorMessage) {
+            // Show the formatted error message from fetchMagentrix
+            console.log(chalk.red(creationResponse.errorMessage));
         } else {
-            console.log(chalk.red('An unknown error occurred during deletion.'));
+            console.log(chalk.red('An unknown error occurred during creation.'));
         }
 
         return;