@magentrix-corp/magentrix-cli 1.0.1 → 1.1.0

package/actions/pull.js

@@ -14,6 +14,7 @@ import { getFileTag } from "../utils/filetag.js";
 import { downloadAssetsZip, listAssets } from "../utils/magentrix/api/assets.js";
 import { downloadAssets, walkAssets } from "../utils/downloadAssets.js";
 import { v4 as uuidv4 } from 'uuid';
+import readlineSync from 'readline-sync';
 
 const config = new Config();
 
@@ -42,7 +43,44 @@ export const pull = async () => {
     // Clear the terminal
     process.stdout.write('\x1Bc');
 
-    // Step 2: Prepare queries for both ActiveClass and ActivePage
+    // Step 2: Check if instance URL has changed (credential switch detected)
+    const lastInstanceUrl = config.read('lastInstanceUrl', { global: false, filename: 'config.json' });
+    const instanceChanged = lastInstanceUrl && lastInstanceUrl !== instanceUrl;
+
+    if (instanceChanged) {
+        console.log(chalk.yellow.bold(`\n⚠️  INSTANCE CHANGE DETECTED`));
+        console.log(chalk.yellow(`Previous instance: ${chalk.cyan(lastInstanceUrl)}`));
+        console.log(chalk.yellow(`New instance:      ${chalk.cyan(instanceUrl)}`));
+        console.log();
+        console.log(chalk.red.bold(`⚠️  WARNING: This will DELETE your existing ${chalk.white(EXPORT_ROOT + '/')} directory!`));
+        console.log(chalk.gray(`This is necessary to prevent mixing files from different instances.`));
+        console.log();
+
+        const confirm = readlineSync.question(
+            chalk.yellow(`Type ${chalk.white.bold('yes')} to continue and delete ${EXPORT_ROOT}/, or ${chalk.white.bold('no')} to cancel: `)
+        );
+
+        if (confirm.trim().toLowerCase() !== 'yes') {
+            console.log(chalk.red('\n❌ Pull cancelled. No files were deleted.'));
+            console.log(chalk.gray(`Tip: To pull from ${chalk.cyan(lastInstanceUrl)}, switch back to those credentials.`));
+            process.exit(0);
+        }
+
+        console.log(chalk.yellow(`\n🗑️  Removing existing ${EXPORT_ROOT}/ directory...`));
+        if (fs.existsSync(EXPORT_ROOT)) {
+            fs.rmSync(EXPORT_ROOT, { recursive: true, force: true });
+        }
+        // Clear the base.json cache as well since it's from a different instance
+        fs.writeFileSync('.magentrix/base.json', JSON.stringify({}));
+        config.save('cachedFiles', {}, { filename: 'fileCache.json' });
+        config.save('trackedFileTags', {}, { filename: 'fileIdIndex.json' });
+        console.log(chalk.green(`✓ Removed ${EXPORT_ROOT}/ directory\n`));
+    }
+
+    // Save the current instance URL for future comparisons
+    config.save('lastInstanceUrl', instanceUrl, { global: false, filename: 'config.json' });
+
+    // Step 3: Prepare queries for both ActiveClass and ActivePage
     const queries = [
         {
             name: "ActiveClass",
@@ -63,7 +101,7 @@ export const pull = async () => {
         );
 
         const assetTree = await downloadAssets(instanceUrl, token.value);
-       
+
         return [
             ...meqlResults,
             assetTree
@@ -74,13 +112,23 @@ export const pull = async () => {
     const processAssets = (records) => {
         for (const record of records) {
             if (record?.Type === 'Folder') {
-                if (record?.Children?.length === 0) continue;
-                processAssets(record.Children);
+                // Cache the folder itself
+                updateBase(
+                    path.join(EXPORT_ROOT, record?.Path),
+                    {
+                        ...record,
+                        Id: path.join(EXPORT_ROOT, record?.Path)
+                    }
+                );
+                // Process children if any
+                if (record?.Children?.length > 0) {
+                    processAssets(record.Children);
+                }
                 continue;
             }
 
             updateBase(
-                path.join(EXPORT_ROOT, record?.Path), 
+                path.join(EXPORT_ROOT, record?.Path),
                 {
                     ...record,
                     Id: path.join(EXPORT_ROOT, record?.Path)
@@ -91,9 +139,6 @@ export const pull = async () => {
 
     processAssets(assets.tree);
 
-    // Remove (clean) the export root directory
-    // fs.rmSync(EXPORT_ROOT, { recursive: true, force: true });
-
     // Check for conflicts and have user select conflict resolution
     const activeClassRecords = (activeClassResult.Records || []).map(record => {
         record.Content = record.Body;

package/actions/setup.js

@@ -9,20 +9,47 @@ const config = new Config();
 
 /**
  * Runs the global setup for the Magentrix CLI.
- * 
+ *
  * Prompts the user for their API key and instance URL if needed,
  * validates credentials by attempting authentication,
  * and saves them to the global config if successful.
- * 
+ *
  * @async
- * @param {boolean} [forceNewData=false] - If true, always prompt for new data, even if values exist.
+ * @param {Object} cliOptions - CLI options passed from command flags
+ * @param {string} [cliOptions.apiKey] - API key from CLI
+ * @param {string} [cliOptions.instanceUrl] - Instance URL from CLI
  * @returns {Promise<{apiKey: string, instanceUrl: string}>} The saved API key and instance URL.
  * @throws {Error} If authentication fails with provided credentials.
  */
-export const setup = async () => {
-    // Prompt for API key and Instance URL if missing or if forceNewData is true
-    const apiKey = await ensureApiKey(true);
-    const instanceUrl = await ensureInstanceUrl(true);
+export const setup = async (cliOptions = {}) => {
+    // Validation for CLI-provided values
+    const urlRegex = /^https:\/\/[a-zA-Z0-9-]+\.magentrix(cloud)?\.com$/;
+
+    if (cliOptions.apiKey) {
+        if (cliOptions.apiKey.trim().length < 12) {
+            throw new Error('--api-key must be at least 12 characters long');
+        }
+        if (/\s/.test(cliOptions.apiKey)) {
+            throw new Error('--api-key cannot contain spaces');
+        }
+    }
+
+    if (cliOptions.instanceUrl) {
+        const trimmedUrl = cliOptions.instanceUrl.trim();
+        if (!urlRegex.test(trimmedUrl)) {
+            throw new Error('--instance-url must be in the form: https://subdomain.magentrixcloud.com (NO http, NO trailing /, NO extra path)');
+        }
+    }
+
+    // Get API key (from CLI or prompt)
+    const apiKey = cliOptions.apiKey
+        ? cliOptions.apiKey.trim()
+        : await ensureApiKey(true);
+
+    // Get instance URL (from CLI or prompt)
+    const instanceUrl = cliOptions.instanceUrl
+        ? cliOptions.instanceUrl.trim()
+        : await ensureInstanceUrl(true);
 
     // Validate credentials by attempting to fetch an access token
     const tokenData = await tryAuthenticate(apiKey, instanceUrl);

package/bin/magentrix.js

@@ -113,9 +113,68 @@ program.configureOutput({
 });
 
 // ── Commands ─────────────────────────────────
-program.command('setup').description('Configure your Magentrix API key').action(withDefault(setup));
+program
+    .command('setup')
+    .description('Configure your Magentrix API key')
+    .option('--api-key <apiKey>', 'Magentrix API key')
+    .option('--instance-url <instanceUrl>', 'Magentrix instance URL (e.g., https://example.magentrixcloud.com)')
+    .action(withDefault(setup));
 program.command('pull').description('Pull files from the remote server').action(withDefault(pull));
-program.command('create').description('Create files locally').action(withDefault(create));
+const createCommand = program
+    .command('create')
+    .description('Create files locally')
+    .option('--type <type>', 'Entity type: class, page, or template')
+    .option('--class-type <classType>', 'Class type: controller, utility, or trigger (for --type class)')
+    .option('--name <name>', 'Name of the file to create')
+    .option('--description <description>', 'Optional description')
+    .option('--entity-id <entityId>', 'Entity ID (required for triggers)')
+    .action(withDefault(create));
+
+// Override help for create command to show options
+createCommand.configureHelp({
+    formatHelp: () => {
+        const divider = chalk.gray('━'.repeat(60));
+        const titleBar = chalk.bold.bgBlue.white(' Magentrix CLI - Create Command ');
+
+        let help = `\n${divider}\n${titleBar}\n${divider}\n\n`;
+        help += `${chalk.dim('Create files locally with optional parameters to bypass interactive prompts')}\n\n`;
+
+        help += `${chalk.bold.yellow('USAGE')}\n`;
+        help += `  ${chalk.cyan('magentrix create')} ${chalk.dim('[options]')}\n\n`;
+
+        help += `${chalk.bold.yellow('OPTIONS')}\n`;
+        const options = [
+            { name: '--type <type>', desc: 'Entity type: class, page, or template' },
+            { name: '--class-type <classType>', desc: 'Class type: controller, utility, or trigger (for --type class)' },
+            { name: '--name <name>', desc: 'Name of the file to create' },
+            { name: '--description <description>', desc: 'Optional description' },
+            { name: '--entity-id <entityId>', desc: 'Entity ID (required for triggers)' },
+            { name: '-h, --help', desc: 'Display this help message' }
+        ];
+
+        const maxNameLen = Math.max(...options.map(o => o.name.length));
+        options.forEach(opt => {
+            const padding = ' '.repeat(maxNameLen - opt.name.length);
+            help += `  ${chalk.cyan(opt.name)}${padding}  ${chalk.dim(opt.desc)}\n`;
+        });
+
+        help += `\n${chalk.bold.yellow('EXAMPLES')}\n`;
+        help += `  ${chalk.dim('# Create a controller non-interactively')}\n`;
+        help += `  ${chalk.cyan('magentrix create --type class --class-type controller --name UserController')}\n\n`;
+        help += `  ${chalk.dim('# Create a trigger')}\n`;
+        help += `  ${chalk.cyan('magentrix create --type class --class-type trigger --entity-id abc123 --name AccountTrigger')}\n\n`;
+        help += `  ${chalk.dim('# Create a page')}\n`;
+        help += `  ${chalk.cyan('magentrix create --type page --name HomePage --description "Main landing page"')}\n\n`;
+        help += `  ${chalk.dim('# Create a template')}\n`;
+        help += `  ${chalk.cyan('magentrix create --type template --name EmailTemplate')}\n\n`;
+        help += `  ${chalk.dim('# Mix interactive and non-interactive (will prompt for missing info)')}\n`;
+        help += `  ${chalk.cyan('magentrix create --name MyClass')}\n`;
+
+        help += `\n${divider}\n`;
+
+        return help;
+    }
+});
 program.command('status').description('Show file conflicts').action(withDefault(status));
 program.command('autopublish').description('Watch & sync changes in real time').action(withDefault(autoPublish));
 program.command('publish').description('Publish pending changes to the remote server').action(withDefault(publish));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magentrix-corp/magentrix-cli",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "CLI tool for synchronizing local files with Magentrix cloud platform",
   "main": "index.js",
   "type": "module",
@@ -8,7 +8,7 @@
     "magentrix": "./bin/magentrix.js"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node tests/all.js"
   },
   "keywords": [
     "magentrix",
@@ -40,6 +40,7 @@
     "chokidar": "^4.0.3",
     "commander": "^14.0.0",
     "diff": "^8.0.2",
+    "dotenv": "^17.2.3",
     "extract-zip": "^2.0.1",
     "fuzzy": "^0.1.3",
     "inquirer": "^12.7.0",

package/utils/assetPaths.js

@@ -0,0 +1,138 @@
+import path from 'path';
+import { EXPORT_ROOT } from '../vars/global.js';
+
+/**
+ * Asset path utilities for handling the difference between local and API paths.
+ *
+ * Local structure:  src/Assets/...
+ * API structure:    /contents/assets/...
+ *
+ * These helpers abstract away the "Contents" prefix requirement for the Magentrix API.
+ */
+
+/**
+ * Convert a local asset path to an API path by adding the 'contents' prefix
+ * and normalizing to lowercase with forward slashes.
+ *
+ * @param {string} localPath - Local file path (e.g., "src/Assets/images/logo.png")
+ * @returns {string} API path (e.g., "/contents/assets/images")
+ *
+ * @example
+ * toApiPath("src/Assets/images/logo.png") // "/contents/assets/images"
+ * toApiPath("src/Assets") // "/contents/assets"
+ */
+export const toApiPath = (localPath) => {
+    // Handle undefined or empty paths
+    if (!localPath) {
+        return '/contents/assets';
+    }
+
+    // Normalize the path and remove the EXPORT_ROOT
+    const normalized = path.normalize(localPath);
+    const relative = normalized.replace(new RegExp(`^${EXPORT_ROOT}[\\\\/]?`), '');
+
+    // Replace 'Assets' with 'contents/assets'
+    const apiPath = relative.replace(/^Assets/i, 'contents/assets');
+
+    // Normalize to forward slashes and lowercase, remove filename
+    let dirPath = path.dirname(apiPath).replace(/\\/g, '/').toLowerCase();
+
+    // Handle edge case where dirname returns '.' for root
+    if (dirPath === '.') {
+        dirPath = 'contents/assets';
+    }
+
+    // Ensure it starts with /
+    return dirPath.startsWith('/') ? dirPath : `/${dirPath}`;
+};
+
+/**
+ * Convert an API path to a local path by removing the 'contents' prefix.
+ * Returns a relative path (without EXPORT_ROOT) that can be joined with EXPORT_ROOT.
+ *
+ * @param {string} apiPath - API path (e.g., "/contents/assets/images/logo.png")
+ * @returns {string} Relative local path (e.g., "Assets/images/logo.png")
+ *
+ * @example
+ * toLocalPath("/contents/assets/images") // "Assets/images"
+ * toLocalPath("/contents/assets") // "Assets"
+ */
+export const toLocalPath = (apiPath) => {
+    // Remove leading slash and 'contents/' prefix
+    const cleaned = apiPath.replace(/^\/+/, '').replace(/^contents\//i, '');
+
+    // Capitalize 'assets' to 'Assets'
+    const withCapitalAssets = cleaned.replace(/^assets/i, 'Assets');
+
+    return withCapitalAssets;
+};
+
+/**
+ * Convert a local folder path to an API path (keeps the folder, doesn't extract parent).
+ * Similar to toApiPath but for folders.
+ *
+ * @param {string} localFolderPath - Local folder path (e.g., "src/Assets/images")
+ * @returns {string} API path (e.g., "/contents/assets/images")
+ *
+ * @example
+ * toApiFolderPath("src/Assets/images") // "/contents/assets/images"
+ * toApiFolderPath("src/Assets") // "/contents/assets"
+ */
+export const toApiFolderPath = (localFolderPath) => {
+    // Handle undefined or empty paths
+    if (!localFolderPath) {
+        return '/contents/assets';
+    }
+
+    // Normalize the path and remove the EXPORT_ROOT
+    const normalized = path.normalize(localFolderPath);
+    const relative = normalized.replace(new RegExp(`^${EXPORT_ROOT}[\\\\/]?`), '');
+
+    // Replace 'Assets' with 'contents/assets'
+    let apiPath = relative.replace(/^Assets/i, 'contents/assets');
+
+    // Normalize to forward slashes and lowercase (but don't get dirname!)
+    apiPath = apiPath.replace(/\\/g, '/').toLowerCase();
+
+    // Handle edge case where path is just 'Assets'
+    if (apiPath === 'contents/assets' || apiPath === '') {
+        return '/contents/assets';
+    }
+
+    // Ensure it starts with /
+    return apiPath.startsWith('/') ? apiPath : `/${apiPath}`;
+};
+
+/**
+ * Check if a local path is within the Assets directory.
+ *
+ * @param {string} localPath - Local file path
+ * @returns {boolean} True if path is within Assets directory
+ *
+ * @example
+ * isAssetPath("src/Assets/images/logo.png") // true
+ * isAssetPath("src/Classes/MyClass.ac") // false
+ */
+export const isAssetPath = (localPath) => {
+    const normalized = path.normalize(localPath);
+    const assetsDir = path.join(EXPORT_ROOT, 'Assets');
+    return normalized.startsWith(assetsDir);
+};
+
+/**
+ * Extract the folder path from a full file path (removes filename).
+ * Returns path relative to Assets root.
+ *
+ * @param {string} filePath - Full file path
+ * @returns {string} Folder path relative to EXPORT_ROOT
+ *
+ * @example
+ * getAssetFolder("src/Assets/images/logo.png") // "Assets/images"
+ * getAssetFolder("src/Assets/logo.png") // "Assets"
+ */
+export const getAssetFolder = (filePath) => {
+    const normalized = path.normalize(filePath);
+    const relative = normalized.replace(new RegExp(`^${EXPORT_ROOT}[\\\\/]?`), '');
+    const dirPath = path.dirname(relative);
+    return dirPath === '.' ? 'Assets' : dirPath;
+};

package/utils/cacher.js

@@ -91,7 +91,7 @@ export const recacheFileIdIndex = async (dir) => {
 export async function walkFiles(dir, settings) {
     const ignore = settings?.ignore || [];
 
-    if (!fs.existsSync(dir)) return;
+    if (!fs.existsSync(dir)) return [];
     let entries = fs.readdirSync(dir, { withFileTypes: true });
     let paths = [];
 
@@ -102,7 +102,10 @@ export async function walkFiles(dir, settings) {
 
         const fullPath = path.join(dir, entry.name);
         if (entry.isDirectory()) {
-            paths.push(...await walkFiles(fullPath, settings));
+            const subPaths = await walkFiles(fullPath, settings);
+            if (subPaths && subPaths.length > 0) {
+                paths.push(...subPaths);
+            }
         } else if (entry.isFile()) {
             paths.push(fullPath);
         }

package/utils/cli/helpers/compare.js

@@ -243,8 +243,10 @@ export async function showCurrentConflicts(rootDir, instanceUrl, token, forceCon
 export async function promptConflictResolution(fileIssues) {
     if (!fileIssues.length) return 'skip';
 
-    // Clear for better UX
-    console.clear();
+    // Clear for better UX (skip in test mode to avoid clearing test output)
+    if (!process.env.MAGENTRIX_TEST_MODE) {
+        console.clear();
+    }
     console.log(
         chalk.bold.yellow(
             `\n${fileIssues.length} file${fileIssues.length > 1 ? 's' : ''} require conflict resolution:\n`

package/utils/downloadAssets.js

@@ -5,6 +5,7 @@ import extract from 'extract-zip';
 import { v4 as uuidv4 } from 'uuid';
 import fspath from 'path';
 import { setFileTag } from "./filetag.js";
+import { toLocalPath } from "./assetPaths.js";
 
 export const walkAssets = async (instanceUrl, token, assetPath) => {
     const assetResults = await listAssets(instanceUrl, token, assetPath);
@@ -14,15 +15,19 @@ export const walkAssets = async (instanceUrl, token, assetPath) => {
         if (asset.Type === 'Folder') {
             walkedAssets.push({
                 ...asset,
-                Path: asset.Path.replace('/contents/assets', '/Contents/Assets'),
+                ApiPath: asset.Path, // Keep original API path
+                Path: toLocalPath(asset.Path), // Convert for local file system
                 Children: await walkAssets(instanceUrl, token, asset.Path),
-                ParentFolder: assetResults.CurrentPath.replace("/contents/assets", "/Contents/Assets"),
+                ParentFolder: toLocalPath(assetResults.CurrentPath),
+                ParentApiPath: assetResults.CurrentPath, // Keep API path for downloads
             })
         } else {
             walkedAssets.push({
                 ...asset,
-                Path: asset.Path.replace("/contents/assets", "/Contents/Assets"),
-                ParentFolder: assetResults.CurrentPath.replace("/contents/assets", "/Contents/Assets"),
+                ApiPath: asset.Path, // Keep original API path
+                Path: toLocalPath(asset.Path), // Convert for local file system
+                ParentFolder: toLocalPath(assetResults.CurrentPath),
+                ParentApiPath: assetResults.CurrentPath, // Keep API path for downloads
             });
         }
     }
@@ -34,7 +39,8 @@ export const downloadAssets = async (instanceUrl, token, path) => {
     const allAssets = await walkAssets(instanceUrl, token, path);
 
     const iterateDownload = async (assets) => {
-        const parentOfAssets = assets?.[0]?.ParentFolder;
+        const parentApiPath = assets?.[0]?.ParentApiPath; // Use API path for API calls
+        const parentLocalFolder = assets?.[0]?.ParentFolder; // Use local path for file system
         const folders = assets.filter(asset => asset.Type === 'Folder');
         const files = assets.filter(asset => asset.Type === 'File');
 
@@ -47,13 +53,13 @@ export const downloadAssets = async (instanceUrl, token, path) => {
             const savedAs = await downloadAssetsZip({
                 baseUrl: instanceUrl,
                 token: token, // "Bearer" prefix added in code
-                path: parentOfAssets,
+                path: parentApiPath, // Use API path for API call
                 names: files.map(file => file.Name),
-                outFile: fspath.join(EXPORT_ROOT, parentOfAssets, 'assets.zip'), // optional
+                outFile: fspath.join(EXPORT_ROOT, parentLocalFolder, 'assets.zip'), // Use local path for file system
             });
 
             await extract(savedAs, {
-                dir: fspath.resolve(fspath.join(EXPORT_ROOT, parentOfAssets))
+                dir: fspath.resolve(fspath.join(EXPORT_ROOT, parentLocalFolder)) // Use local path for extraction
             });
 
             // for (const file of files) {

package/utils/magentrix/api/assets.js

@@ -80,7 +80,7 @@ export const deleteAsset = async (instanceUrl, token, path = '/contents/assets',
     if (!path) throw new Error("Path is required when deleting assets.");
     if (!Array.isArray(names) || names?.length === 0) throw new Error("At least one file name is required when deleting static assets.");
 
-    let reqPath = `/api/3.0/staticassets?path=${path}&names=${names.join(",")}`;
+    let reqPath = `/api/3.0/staticassets?path=${encodeURIComponent(path)}&names=${names.join(",")}`;
 
     const response = await fetchMagentrix({
         instanceUrl,
@@ -93,6 +93,26 @@ export const deleteAsset = async (instanceUrl, token, path = '/contents/assets',
     return response;
 }
 
+export const createFolder = async (instanceUrl, token, path = '/contents/assets', name) => {
+    if (!instanceUrl || !token) {
+        throw new Error('Missing required Magentrix instanceUrl or token');
+    }
+
+    if (!name) throw new Error("Folder name is required when creating a folder.");
+
+    let reqPath = `/api/3.0/staticassets/folder?path=${encodeURIComponent(path)}&name=${encodeURIComponent(name)}`;
+
+    const response = await fetchMagentrix({
+        instanceUrl,
+        token,
+        path: reqPath,
+        method: "POST",
+        returnErrorObject: true
+    });
+
+    return response;
+}
+
 /**
  * Download multiple static assets as a ZIP.
  * @param {object} opts

package/utils/magentrix/api/retrieveEntity.js

@@ -3,7 +3,7 @@ import { fetchMagentrix } from "../fetch.js";
 /**
  * Lists all entities available from the Magentrix API.
  *
- * Makes an authenticated GET request to `/api/3.0/entity` to retrieve metadata 
+ * Makes an authenticated GET request to `/api/3.0/entity` to retrieve metadata
  * about all available entities (objects) in the Magentrix instance.
  *
  * Handles and throws both network errors and API-level errors with detailed messages.
@@ -30,3 +30,57 @@ export const listEntities = async (instanceUrl, token) => {
 
     return data;
 };
+
+/**
+ * Retrieves a specific ActiveClass or ActivePage entity by ID from Magentrix via the REST API.
+ *
+ * @async
+ * @function retrieveEntity
+ * @param {string} instanceUrl - The base URL of the Magentrix instance (e.g. "https://your.magentrix.com").
+ * @param {string} token - The OAuth2 bearer token for authentication.
+ * @param {string} entityName - The Magentrix entity type. Allowed: "ActiveClass" or "ActivePage" (case-insensitive).
+ * @param {string} recordId - The unique Magentrix record ID to retrieve.
+ * @returns {Promise<Object>} The API response object containing the record data.
+ * @throws {Error} If required parameters are missing, entityName is invalid, or recordId is not provided.
+ *
+ * @example
+ * const record = await retrieveEntity(
+ *   "https://your.magentrix.com",
+ *   "yourToken",
+ *   "ActiveClass",
+ *   "06bdc45e-8222-44f5-9ed2-40f5a7bc6cb3"
+ * );
+ */
+export const retrieveEntity = async (instanceUrl, token, entityName, recordId) => {
+    // --- Validate required parameters ---
+    if (!instanceUrl || typeof instanceUrl !== 'string') {
+        throw new Error('Missing or invalid Magentrix instanceUrl');
+    }
+    if (!token || typeof token !== 'string') {
+        throw new Error('Missing or invalid Magentrix token');
+    }
+    if (!entityName || typeof entityName !== 'string') {
+        throw new Error("Missing or invalid 'entityName' (must be 'ActiveClass' or 'ActivePage')");
+    }
+    if (!recordId || typeof recordId !== 'string') {
+        throw new Error("Missing or invalid 'recordId' (must be a Magentrix record GUID string)");
+    }
+
+    // --- Validate entity type ---
+    const allowedEntities = ['activeclass', 'activepage'];
+    const entity = entityName.trim().toLowerCase();
+    if (!allowedEntities.includes(entity)) {
+        throw new Error("Invalid 'entityName'. Allowed: 'ActiveClass' or 'ActivePage'");
+    }
+
+    // --- Make GET request to Magentrix API ---
+    const response = await fetchMagentrix({
+        instanceUrl,
+        token,
+        path: `/api/3.0/entity/${entity}/${recordId}`,
+        method: "GET",
+        returnErrorObject: true
+    });
+
+    return response;
+};

package/utils/updateFileBase.js

@@ -59,10 +59,15 @@ export const updateBase = (filePath, record, actualPath = '', contentSnapshot =
 
     // Get file stats for mtime
     const fileStats = fs.statSync(fileSystemLocation);
+    const isDirectory = fileStats.isDirectory();
 
     // Use snapshot if provided (to avoid race conditions), otherwise read from disk
     let fileContent, contentHash;
-    if (contentSnapshot && contentSnapshot.content) {
+    if (isDirectory) {
+        // Folders don't have content
+        fileContent = '';
+        contentHash = '';
+    } else if (contentSnapshot && contentSnapshot.content) {
         // Use the snapshot of what was actually published
         fileContent = contentSnapshot.content;
         contentHash = contentSnapshot.hash;
@@ -79,7 +84,7 @@ export const updateBase = (filePath, record, actualPath = '', contentSnapshot =
     const saveData = {
         lastModified: fileStats.mtimeMs,
         contentHash,
-        compressedContent: compressString(fileContent),
+        compressedContent: isDirectory ? '' : compressString(fileContent),
         recordId: record.Id,
         type: record.Type,
         filePath,
@@ -87,7 +92,7 @@ export const updateBase = (filePath, record, actualPath = '', contentSnapshot =
         lastKnownPath: path.resolve(filePath)
     }
 
-    if (saveData.type === 'File') delete saveData.compressedContent;
+    if (saveData.type === 'File' || saveData.type === 'Folder') delete saveData.compressedContent;
 
     config.save(
         record.Id,

package/vars/global.js

@@ -3,6 +3,7 @@ import { sha256 } from '../utils/hash.js'; // Or wherever your hash function liv
 export const CWD = process.cwd();
 export const HASHED_CWD = sha256(CWD);
 export const EXPORT_ROOT = "src";
+export const ASSETS_DIR = "Assets"; // Local directory name for static assets (API uses /contents/assets)
 
 /**
      * Maps Magentrix Type fields to local folder names and extensions.