@magentrix-corp/magentrix-cli 1.0.0

package/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2025 Magentrix Corporation
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary and confidential information of Magentrix Corporation.
+
+Permission is hereby granted to use this Software solely for the purpose of
+interacting with Magentrix services and platforms.
+
+RESTRICTIONS:
+- You may NOT redistribute, sublicense, or sell copies of the Software
+- You may NOT modify, merge, or create derivative works from the Software
+- You may NOT use the Software for any purpose other than interacting with
+  Magentrix services
+- The Software may only be installed and used in accordance with Magentrix's
+  terms of service
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,471 @@
+# MagentrixCLI User Guide
+
+A complete guide to installing and using MagentrixCLI for syncing your local development files with Magentrix cloud platform.
+
+---
+
+## What is MagentrixCLI?
+
+MagentrixCLI is a command-line tool that lets you:
+- Download your Magentrix code files to work on them locally
+- Upload your local changes back to Magentrix
+- Create new files with proper templates
+- Keep everything synchronized automatically
+- Work with your favorite code editor instead of the web interface
+
+---
+
+## Prerequisites
+
+Before you start, make sure you have:
+
+1. **Node.js installed** (version 20 or higher)
+   - Download from [nodejs.org](https://nodejs.org/)
+   - Verify installation: `node --version`
+
+2. **Access to a Magentrix instance**
+   - You need the URL (e.g., `https://yourcompany.magentrixcloud.com`)
+
+3. **API Key from Magentrix**
+   - Get this from your Magentrix administrator or system settings
+   - It looks like a long string of characters
+
+---
+
+## Installation
+
+### Global Installation (Recommended)
+Install the package globally so you can use it from anywhere:
+
+```bash
+npm install -g @magentrix-corp/magentrix-cli
+```
+
+### Local Installation (Alternative)
+If you prefer to install it locally in your project:
+
+```bash
+npm install @magentrix-corp/magentrix-cli
+```
+
+Then run commands using:
+```bash
+npx magentrix <command>
+```
+
+### Verify Installation
+Check that the installation worked:
+```bash
+magentrix --version
+```
+
+You should see the version number displayed.
+
+---
+
+## First Time Setup
+
+### Step 1: Configure Your Credentials
+Run this command to set up your connection to Magentrix:
+
+```bash
+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`)
+
+The tool will test your credentials and save them securely. It will also automatically configure VS Code file associations for syntax highlighting of Magentrix file types (.ac, .ctrl, .trigger, .aspx files).
+
+### Editor Support
+- **VS Code (Recommended)**: The tool automatically sets up syntax highlighting for all Magentrix file types during setup
+- **Other Editors**: The tool works with any text editor (Sublime Text, Atom, Vim, etc.) but you'll need to configure syntax highlighting manually
+- **Terminal Only**: You can use the tool entirely from the command line without any editor
+
+### Step 2: Download Your Files
+Pull all your existing files from Magentrix:
+
+```bash
+magentrix pull
+```
+
+This creates a `src` folder with all your files organized into:
+- `Classes/` - Your utility classes (`.ac` files)
+- `Controllers/` - Your controllers (`.ctrl` files)
+- `Triggers/` - Your trigger code (`.trigger` files)
+- `Pages/` - Your ASPX pages (`.aspx` files)
+- `Templates/` - Your templates (`.aspx` files)
+
+---
+
+## Daily Usage
+
+### Check Connection Status
+```bash
+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.
+
+### 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.
+**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
+
+### Check Status and Conflicts
+```bash
+magentrix status
+```
+**What it does**: Compares your local files with the server versions and shows you exactly what's different - which files have conflicts, what's been added, modified, or deleted. Does NOT make any changes.
+**When to use**:
+- Before running `publish` to see what will be uploaded
+- To check for conflicts without downloading anything
+- To verify your local workspace is in sync with server
+
+### Upload Your Changes to Server
+```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.
+**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
+
+### Real-Time Development Mode
+```bash
+magentrix autopublish
+```
+**What it does**: Watches your files for changes and automatically uploads and compiles them on the server whenever you save a file. Shows compilation status and any errors in the terminal in real-time. Can take some time to sync each file.
+**When to use**:
+- During active development when you want immediate feedback
+- When testing changes and want to see results right away
+- For iterative development where you're making frequent small changes
+**Note**: Best for real-time development but slower than batch publishing. Press Ctrl+C to stop.
+
+---
+
+## Creating New Files
+
+### Interactive File Creation
+```bash
+magentrix create
+```
+
+This starts an interactive wizard:
+
+1. **Choose what to create:**
+   - ActiveClass (for Controllers, Classes, or Triggers)
+   - ActivePage (for Pages or Templates)
+
+2. **For Classes/Controllers/Triggers:**
+   - Select the type (Controller, Class, or Trigger)
+   - Enter the name
+   - Add optional description
+   - For Triggers: Search and select the target entity
+
+3. **For Pages/Templates:**
+   - Choose Page or Template
+   - Enter the name
+   - Add optional description
+
+The tool creates the file both locally and on your Magentrix server with proper templates.
+
+---
+
+## Working with Files
+
+### File Organization
+Your files are organized like this:
+```
+src/
+├── Classes/         # Utility classes (*.ac files)
+├── Controllers/     # Controllers (*.ctrl files)
+├── Triggers/        # Trigger code (*.trigger files)
+├── Pages/           # ASPX pages (*.aspx files)
+└── Templates/       # Templates (*.aspx files)
+```
+
+### File Extensions
+- `.ac` - Classes
+- `.ctrl` - Controllers
+- `.trigger` - Triggers
+- `.aspx` - Pages and Templates
+
+### Editing Files
+1. Open any file in your favorite editor (VS Code, Sublime, etc.)
+2. Make your changes
+3. Save the file
+4. Run `magentrix publish` to upload changes
+   - Or use `magentrix autopublish` for automatic uploads
+
+---
+
+## Handling Conflicts
+
+When files have changed both locally and on the server, you'll see conflict options:
+
+### Option 1: Overwrite Local
+Replaces your local files with server versions (you lose local changes).
+
+### Option 2: Skip Conflicts
+Keeps your local files, ignores server changes.
+
+### Option 3: Manual Review
+Review each conflict individually and choose what to keep.
+
+**Tip**: Always run `magentrix pull` before making changes to avoid conflicts.
+
+---
+
+## Common Workflows
+
+### Starting Your Day
+```bash
+magentrix pull          # Get latest files
+magentrix status        # Check what's different
+# Work on your files...
+magentrix publish       # Upload your changes
+```
+
+### Real-Time Development
+```bash
+magentrix pull          # Get latest
+magentrix autopublish   # Start auto-sync
+# Edit files - they upload automatically when saved
+# Press Ctrl+C to stop auto-sync
+```
+
+### Creating New Features
+```bash
+magentrix create        # Create new files with wizard
+# Edit the created files...
+magentrix publish       # Upload when ready
+```
+
+### Before Going Home
+```bash
+magentrix publish       # Make sure all changes are uploaded
+magentrix status        # Verify everything is in sync
+```
+
+---
+
+## Using Git Alongside MagentrixCLI
+
+### Important: Separate Systems
+MagentrixCLI and Git are **completely separate** tools that don't integrate with each other. Here's how to use them together effectively:
+
+### What Each Tool Does
+- **MagentrixCLI**: Syncs your local files with your Magentrix server (for deployment and compilation)
+- **Git**: Tracks your code changes and syncs with your source control repository (for version control and collaboration)
+
+### Recommended Workflow
+
+#### 1. Set Up Both Systems
+```bash
+# Initialize git repository (if not already done)
+git init
+git remote add origin <your-repo-url>
+
+# Set up MagentrixCLI
+magentrix setup
+magentrix pull
+```
+
+#### 2. Daily Development Flow
+```bash
+# Start of day - get latest from both systems
+git pull                    # Get latest code from repository
+magentrix pull             # Get latest files from Magentrix server
+
+# Work on your files...
+# Save changes in editor
+
+# Commit to git first (for version control)
+git add .
+git commit -m "Your commit message"
+git push                   # Share with team via git
+
+# Then deploy to Magentrix server
+magentrix publish          # Deploy to server for testing/production
+```
+
+#### 3. Git Repository Setup
+Add these to your `.gitignore` file:
+```
+# MagentrixCLI cache files - don't commit these
+.magentrix/
+node_modules/
+```
+
+But **DO commit**:
+```
+src/                       # Your actual code files
+package.json              # If you have one
+README.md                 # Documentation
+```
+
+### Best Practices
+
+#### Use Git for Version Control
+- **Commit often**: Commit logical chunks of work with meaningful messages
+- **Branch for features**: Create branches for new features or major changes
+- **Code reviews**: Use pull requests for team collaboration
+
+#### Use MagentrixCLI for Deployment
+- **Test locally first**: Make sure your code works before deploying
+- **Deploy after committing**: Always commit to git before deploying to Magentrix
+- **Use status**: Check `magentrix status` before deploying
+
+### Example Team Workflow
+
+#### Developer A
+```bash
+git checkout -b feature/new-controller
+# Make changes to files
+git add .
+git commit -m "Add new customer controller"
+git push origin feature/new-controller
+# Create pull request
+
+# After PR approval and merge:
+git checkout main
+git pull
+magentrix publish          # Deploy merged changes
+```
+
+#### Developer B
+```bash
+git pull                   # Get A's changes
+magentrix pull            # Get any server changes
+# Continue working with latest code
+```
+
+### Conflict Resolution
+
+#### Git Conflicts (Code Level)
+- Resolve using git merge tools
+- Coordinate with teammates
+- Use standard git conflict resolution
+
+#### Magentrix Conflicts (Server Level)
+- Use `magentrix status` to identify conflicts
+- Choose resolution strategy (overwrite, skip, manual)
+- Independent of git - handled by MagentrixCLI
+
+### Why Keep Them Separate
+- **Git**: Permanent history, branching, collaboration, code reviews
+- **MagentrixCLI**: Live server deployment, compilation, testing
+- **Different purposes**: Version control vs deployment
+- **Different timing**: Git for development process, MagentrixCLI for deployment
+
+This separation gives you the best of both worlds - robust version control AND seamless deployment!
+
+---
+
+## Troubleshooting
+
+### "Authentication failed"
+- Check your API key is correct
+- Verify your instance URL is right
+- Run `magentrix setup` again
+
+### "No files found" or empty src folder
+- Run `magentrix pull` to download files
+- Check you have permission to access the Magentrix instance
+
+### Files not uploading
+- Check file permissions
+- Ensure you're in the right directory (where `src` folder is)
+- Try `magentrix status` to see what's different
+
+### "File is currently compiling" message
+- Wait for the current upload to finish
+- The tool prevents conflicts by processing one file at a time
+
+### Lost connection during autopublish
+- Press Ctrl+C to stop autopublish
+- Run `magentrix publish` to upload any remaining changes
+- Restart with `magentrix autopublish`
+
+---
+
+## Tips & Best Practices
+
+### 1. Always Pull First
+Run `magentrix pull` before starting work to get the latest files.
+
+### 2. Check Status Before Publishing
+Use `magentrix status` to see what will change before running `magentrix publish`.
+
+### 3. Use Autopublish for Active Development
+When actively coding, `magentrix autopublish` saves time by auto-uploading changes.
+
+### 4. Backup Important Work
+The tool is reliable, but always have backups of critical code.
+
+### 5. Organize Your Workspace
+Keep your project folder clean and organized. The tool works best with the standard file structure.
+
+### 6. Use Descriptive Names
+When creating new files, use clear, descriptive names that follow your team's naming conventions.
+
+---
+
+## Configuration Files
+
+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
+
+### Project Settings
+- **Location**: `.magentrix/` folder in your project
+- **Contains**: File mappings, sync status, and local cache
+
+**Note**: These folders are created automatically. Don't delete them unless you want to reconfigure everything.
+
+---
+
+## Getting Help
+
+### Built-in Help
+```bash
+magentrix --help        # Show all commands
+magentrix pull --help   # Help for specific command
+```
+
+### Check Your Setup
+```bash
+magentrix               # Shows connection status
+magentrix status        # Shows sync status
+```
+
+### Common Commands Summary
+- `magentrix setup` - Configure credentials
+- `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
+
+---
+
+## What's Next?
+
+Once you're comfortable with basic usage:
+
+1. **Set up your preferred editor** with syntax highlighting for your file types
+2. **Learn the autopublish workflow** for faster development
+3. **Explore conflict resolution** if you work in a team
+4. **Check out templates** created by the `create` command to understand best practices
+
+Happy coding with MagentrixCLI! 🚀