@magentrix-corp/magentrix-cli 1.0.0 → 1.1.0

package/README.md

@@ -63,9 +63,59 @@ You should see the version number displayed.
 
 ---
 
+## Updating the Package
+
+To update MagentrixCLI to the latest version:
+
+### Global Installation Update
+If you installed globally (recommended):
+
+```bash
+npm update -g @magentrix-corp/magentrix-cli
+```
+
+Or to ensure you get the absolute latest version:
+
+```bash
+npm install -g @magentrix-corp/magentrix-cli@latest
+```
+
+### Local Installation Update
+If you installed locally in your project:
+
+```bash
+npm update @magentrix-corp/magentrix-cli
+```
+
+Or for the latest version:
+
+```bash
+npm install @magentrix-corp/magentrix-cli@latest
+```
+
+### Check for Updates
+To see if you're running the latest version:
+
+```bash
+# Check your current version
+magentrix --version
+
+# Check the latest available version on npm
+npm view @magentrix-corp/magentrix-cli version
+```
+
+### After Updating
+Your configuration and local files are preserved during updates. You don't need to run `magentrix setup` again unless there are breaking changes (which will be noted in release notes).
+
+**Note**: It's a good practice to check for updates periodically to get the latest features, bug fixes, and performance improvements.
+
+---
+
 ## First Time Setup
 
 ### Step 1: Configure Your Credentials
+
+#### Interactive Setup
 Run this command to set up your connection to Magentrix:
 
 ```bash
@@ -76,6 +126,17 @@ You'll be prompted for:
 - **API Key**: Paste your Magentrix API key
 - **Instance URL**: Enter your Magentrix URL (like `https://yourcompany.magentrixcloud.com`)
 
+#### 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
+```
+
+**Available flags:**
+- `--api-key <apiKey>` - Your Magentrix API key
+- `--instance-url <instanceUrl>` - Your Magentrix instance URL
+
 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
@@ -96,6 +157,7 @@ This creates a `src` folder with all your files organized into:
 - `Triggers/` - Your trigger code (`.trigger` files)
 - `Pages/` - Your ASPX pages (`.aspx` files)
 - `Templates/` - Your templates (`.aspx` files)
+- `Assets/` - Your static assets (images, CSS, JavaScript, etc.)
 
 ---
 
@@ -132,7 +194,7 @@ 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.
+**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.
 **When to use**:
 - After you've finished making changes and want to deploy them
 - At the end of your work session
@@ -142,7 +204,7 @@ magentrix publish
 ```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.
+**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. Works with both code files and static assets. 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
@@ -177,6 +239,43 @@ This starts an interactive wizard:
 
 The tool creates the file both locally and on your Magentrix server with proper templates.
 
+### Non-Interactive File Creation
+For automation or scripting, you can provide all parameters via command-line flags:
+
+#### Create a Controller
+```bash
+magentrix create --type class --class-type controller --name UserController --description "Handles user operations"
+```
+
+#### Create a Utility Class
+```bash
+magentrix create --type class --class-type utility --name EmailHelper --description "Email utility functions"
+```
+
+#### Create a Trigger
+```bash
+magentrix create --type class --class-type trigger --entity-id ENTITY_ID --name AccountTrigger --description "Account trigger logic"
+```
+
+#### Create a Page
+```bash
+magentrix create --type page --name Dashboard --description "Main dashboard page"
+```
+
+#### Create a Template
+```bash
+magentrix create --type template --name EmailTemplate --description "Email notification template"
+```
+
+**Available flags:**
+- `--type <type>` - Entity type: `class`, `page`, or `template`
+- `--class-type <classType>` - For classes: `controller`, `utility`, or `trigger`
+- `--name <name>` - Name of the file to create
+- `--description <description>` - Optional description
+- `--entity-id <entityId>` - Required for triggers: the entity ID to attach the trigger to
+
+**Tip**: You can mix interactive and non-interactive modes. For example, provide just the `--name` flag and the tool will prompt you for the rest.
+
 ---
 
 ## Working with Files
@@ -189,7 +288,9 @@ src/
 ├── Controllers/     # Controllers (*.ctrl files)
 ├── Triggers/        # Trigger code (*.trigger files)
 ├── Pages/           # ASPX pages (*.aspx files)
-└── Templates/       # Templates (*.aspx files)
+├── Templates/       # Templates (*.aspx files)
+└── Contents/
+    └── Assets/      # Static assets (images, CSS, JS, etc.)
 ```
 
 ### File Extensions
@@ -207,6 +308,63 @@ src/
 
 ---
 
+## Working with Static Assets
+
+### What Are Static Assets?
+Static assets are non-code files like images, CSS stylesheets, JavaScript files, and other resources that your Magentrix application uses.
+
+### Asset Organization
+All static assets are stored in the `src/Contents/Assets/` directory. You can organize them into subfolders:
+
+```
+src/Contents/Assets/
+├── images/
+│   ├── logo.png
+│   └── banner.jpg
+├── css/
+│   └── custom-styles.css
+└── js/
+    └── helpers.js
+```
+
+### Working with Assets
+
+#### Downloading Assets
+```bash
+magentrix pull
+```
+Downloads all static assets from the server along with your code files. The folder structure is preserved.
+
+#### Adding New Assets
+1. Place your files in `src/Contents/Assets/` (or a subfolder)
+2. Run `magentrix publish` to upload them
+   - Or use `magentrix autopublish` for automatic uploads
+
+#### Updating Assets
+1. Edit or replace the file locally in `src/Contents/Assets/`
+2. Run `magentrix publish` to upload the updated version
+   - Or use `magentrix autopublish` for automatic uploads
+
+#### Deleting Assets
+1. Delete the file from `src/Contents/Assets/`
+2. Run `magentrix publish` to remove it from the server
+
+### Supported File Types
+The tool supports all file types including:
+- Images: `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.ico`
+- Stylesheets: `.css`
+- Scripts: `.js`
+- Documents: `.pdf`, `.txt`, `.json`
+- Any other file type you need
+
+### Important Notes
+- Assets are synced alongside code files
+- Folder structures are preserved when syncing
+- Large files are handled efficiently using batch operations
+- Binary files (like images) are fully supported
+
+---
+
 ## Handling Conflicts
 
 When files have changed both locally and on the server, you'll see conflict options:

package/actions/autopublish.v2.js

@@ -117,11 +117,11 @@ const readFileSafe = (filePath) => {
 };
 
 /**
- * Checks if file is within Contents/Assets (static asset)
+ * Checks if file is within Assets (static asset)
  */
 const isStaticAsset = (filePath) => {
     const normalizedPath = path.normalize(filePath);
-    return normalizedPath.includes(path.join('Contents', 'Assets'));
+    return normalizedPath.includes(path.join('Assets'));
 };
 
 /**

package/actions/create.js

@@ -10,6 +10,7 @@ import fs from 'fs';
 import chalk from 'chalk';
 import { setFileTag } from "../utils/filetag.js";
 import { updateBase } from "../utils/updateFileBase.js";
+import { sha256 } from "../utils/hash.js";
 
 // Credentials and entity cache (module-scope for re-use during prompt session)
 let credentials = {};
@@ -57,42 +58,68 @@ const searchEntities = async (term = '') => {
 
 /**
  * CLI prompt flow for creating an ActiveClass record.
- * 
+ *
  * - Prompts for type (Controller, Utility, or Trigger)
  * - For Trigger, also prompts for target entity selection (searchable)
  * - Prompts for class name and optional description
- * 
+ *
  * @async
+ * @param {Object} options - CLI options to bypass prompts
  * @returns {Promise<Object>} The creation payload for ActiveClass.
  */
-const createActiveClass = async () => {
-    const classType = await select({
-        message: "Select ActiveClass type:",
-        choices: [
-            { name: "Controller", value: "Controller" },
-            { name: "Class", value: "Utility" },
-            { name: "Trigger", value: "Trigger" }
-        ]
-    });
+const createActiveClass = async (options = {}) => {
+    let classType = options.classType;
+
+    // Normalize class type from CLI format to internal format
+    if (classType) {
+        const typeMap = {
+            'controller': 'Controller',
+            'utility': 'Utility',
+            'class': 'Utility',
+            'trigger': 'Trigger'
+        };
+        classType = typeMap[classType.toLowerCase()] || classType;
+    }
+
+    if (!classType) {
+        classType = await select({
+            message: "Select ActiveClass type:",
+            choices: [
+                { name: "Controller", value: "Controller" },
+                { name: "Class", value: "Utility" },
+                { name: "Trigger", value: "Trigger" }
+            ]
+        });
+    }
 
     if (classType === "Trigger") {
-        // Ensure entity list is loaded for search prompt
-        await loadEntities();
+        let entityId = options.entityId;
 
-        const entityId = await search({
-            message: "Search and select entity for this Trigger:",
-            source: searchEntities,
-            pageSize: 8
-        });
+        if (!entityId) {
+            // Ensure entity list is loaded for search prompt
+            await loadEntities();
 
-        const className = await input({
-            message: "Trigger class name:",
-            validate: (input) => input.length > 0 || "Please enter a class name"
-        });
+            entityId = await search({
+                message: "Search and select entity for this Trigger:",
+                source: searchEntities,
+                pageSize: 8
+            });
+        }
 
-        const description = await input({
-            message: "Description (optional):"
-        });
+        let className = options.name;
+        if (!className) {
+            className = await input({
+                message: "Trigger class name:",
+                validate: (input) => input.length > 0 || "Please enter a class name"
+            });
+        }
+
+        let description = options.description;
+        if (description === undefined) {
+            description = await input({
+                message: "Description (optional):"
+            });
+        }
 
         return {
             type: "ActiveClass",
@@ -106,14 +133,20 @@ const createActiveClass = async () => {
     const hint = classType === "Controller" ? "(without controller keyword)" : ""
 
     // Flow for Controller or Utility
-    const className = await input({
-        message: `${classType} class name ${hint}:`,
-        validate: (input) => input.length > 0 || "Please enter a class name"
-    });
+    let className = options.name;
+    if (!className) {
+        className = await input({
+            message: `${classType} class name ${hint}:`,
+            validate: (input) => input.length > 0 || "Please enter a class name"
+        });
+    }
 
-    const description = await input({
-        message: "Description (optional):"
-    });
+    let description = options.description;
+    if (description === undefined) {
+        description = await input({
+            message: "Description (optional):"
+        });
+    }
 
     return {
         type: "ActiveClass",
@@ -125,29 +158,50 @@ const createActiveClass = async () => {
 
 /**
  * CLI prompt flow for creating an ActivePage record.
- * 
+ *
  * - Prompts for page name and optional description.
- * 
+ *
  * @async
+ * @param {Object} options - CLI options to bypass prompts
+ * @param {string} options.pageType - Pre-determined page type (Page or Template)
  * @returns {Promise<Object>} The creation payload for ActivePage.
  */
-const createActivePage = async () => {
-    const pageType = await select({
-        message: "Select ActivePage type:",
-        choices: [
-            { name: "Page", value: "Page" },
-            { name: "Template", value: "Template" }
-        ]
-    });
+const createActivePage = async (options = {}) => {
+    let pageType = options.pageType;
+
+    // Normalize page type from CLI format to internal format
+    if (pageType) {
+        const typeMap = {
+            'page': 'Page',
+            'template': 'Template'
+        };
+        pageType = typeMap[pageType.toLowerCase()] || pageType;
+    }
 
-    const pageName = await input({
-        message: `${pageType} name:`,
-        validate: (input) => input.length > 0 || `Please enter a ${pageType.toLowerCase()} name`
-    });
+    if (!pageType) {
+        pageType = await select({
+            message: "Select ActivePage type:",
+            choices: [
+                { name: "Page", value: "Page" },
+                { name: "Template", value: "Template" }
+            ]
+        });
+    }
 
-    const description = await input({
-        message: "Description (optional):"
-    });
+    let pageName = options.name;
+    if (!pageName) {
+        pageName = await input({
+            message: `${pageType} name:`,
+            validate: (input) => input.length > 0 || `Please enter a ${pageType.toLowerCase()} name`
+        });
+    }
+
+    let description = options.description;
+    if (description === undefined) {
+        description = await input({
+            message: "Description (optional):"
+        });
+    }
 
     return {
         type: pageType,
@@ -193,24 +247,63 @@ const saveToFile = async (entityType, formattedData, recordId) => {
 
     // Add a file tag so we can keep track of file changes
     await setFileTag(filePath, recordId);
-    updateBase(filePath, { Id: recordId, Type: mapKey }); // Update base
+
+    // Update base with content snapshot to ensure cache is in sync
+    const contentHash = sha256(fileContent);
+    updateBase(
+        filePath,
+        { Id: recordId, Type: mapKey },
+        '',
+        { content: fileContent, hash: contentHash }
+    );
 
     return filePath;
 };
 
 /**
  * Main CLI handler for `magentrix create`.
- * 
+ *
  * - Ensures valid Magentrix credentials.
  * - Prompts user to choose entity type (ActiveClass or ActivePage).
  * - Runs the appropriate prompt flow to gather data.
  * - Logs (or sends) the resulting payload.
- * 
+ *
  * @async
  * @function create
+ * @param {Object} cliOptions - Options passed from CLI flags
  * @returns {Promise<void>}
  */
-export const create = async () => {
+export const create = async (cliOptions = {}) => {
+    // Validate CLI options
+    if (cliOptions.type) {
+        const validTypes = ['class', 'page', 'template'];
+        if (!validTypes.includes(cliOptions.type.toLowerCase())) {
+            throw new Error(`Invalid --type: "${cliOptions.type}". Valid options are: ${validTypes.join(', ')}`);
+        }
+    }
+
+    if (cliOptions.classType) {
+        const validClassTypes = ['controller', 'utility', 'class', 'trigger'];
+        if (!validClassTypes.includes(cliOptions.classType.toLowerCase())) {
+            throw new Error(`Invalid --class-type: "${cliOptions.classType}". Valid options are: ${validClassTypes.join(', ')}`);
+        }
+
+        // Ensure --class-type is only used with --type class
+        if (cliOptions.type && cliOptions.type.toLowerCase() !== 'class') {
+            throw new Error('--class-type can only be used with --type class');
+        }
+    }
+
+    if (cliOptions.entityId) {
+        // Ensure --entity-id is only used with triggers
+        if (cliOptions.classType && cliOptions.classType.toLowerCase() !== 'trigger') {
+            throw new Error('--entity-id can only be used with --class-type trigger');
+        }
+        if (!cliOptions.classType) {
+            console.log(chalk.yellow('⚠️  Warning: --entity-id provided without --class-type trigger. It will be ignored unless you select Trigger interactively.'));
+        }
+    }
+
     // Clear the terminal
     process.stdout.write('\x1Bc');
 
@@ -219,21 +312,44 @@ export const create = async () => {
         return await ensureValidCredentials();
     });
 
-    // 2. Prompt user to select the type of entity to create
-    const entityType = await select({
-        message: "What would you like to create?",
-        choices: [
-            { name: "ActiveClass (Controller, Class, Trigger)", value: "ActiveClass" },
-            { name: "ActivePage (ASPX Page)", value: "ActivePage" },
-        ]
-    });
+    // 2. Determine entity type (from CLI or prompt)
+    let entityType;
+    let pageType;
+
+    if (cliOptions.type) {
+        const typeMap = {
+            'class': 'ActiveClass',
+            'page': 'ActivePage',
+            'template': 'ActivePage'
+        };
+        entityType = typeMap[cliOptions.type.toLowerCase()];
+
+        // If template was specified, set the pageType
+        if (cliOptions.type.toLowerCase() === 'template') {
+            pageType = 'Template';
+        } else if (cliOptions.type.toLowerCase() === 'page') {
+            pageType = 'Page';
+        }
+
+        if (!entityType) {
+            throw new Error(`Invalid type: ${cliOptions.type}. Valid types are: class, page, template`);
+        }
+    } else {
+        entityType = await select({
+            message: "What would you like to create?",
+            choices: [
+                { name: "ActiveClass (Controller, Class, Trigger)", value: "ActiveClass" },
+                { name: "ActivePage (ASPX Page)", value: "ActivePage" },
+            ]
+        });
+    }
 
     // 3. Build payload via relevant prompt flow
     let result;
     if (entityType === 'ActiveClass') {
-        result = await createActiveClass();
+        result = await createActiveClass(cliOptions);
     } else if (entityType === 'ActivePage') {
-        result = await createActivePage();
+        result = await createActivePage({ ...cliOptions, pageType });
     } else {
         // Unknown
         throw new Error("Unknown type selected.");
@@ -302,7 +418,7 @@ export const create = async () => {
         const errors = creationResponse.errors || [];
 
         if (errors.length > 0) {
-            errors.forEach((err, i) => {
+            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);