@magentrix-corp/magentrix-cli 1.0.0

package/utils/magentrix/fetch.js

@@ -0,0 +1,154 @@
+/**
+ * Checks if a request body should be JSON-stringified.
+ * Excludes FormData, Blob, ArrayBuffer, URLSearchParams, and typed arrays.
+ * @param {any} body
+ * @returns {boolean}
+ */
+function isJsonBody(body) {
+    return (
+        typeof body === 'object' &&
+        body !== null &&
+        !(body instanceof FormData) &&
+        !(body instanceof Blob) &&
+        !(body instanceof ArrayBuffer) &&
+        !(body instanceof URLSearchParams) &&
+        !ArrayBuffer.isView(body) // covers Uint8Array, etc.
+    );
+}
+
+/**
+ * Fetch helper for Magentrix API.
+ * Handles network, HTTP, and API-level errors with detailed messages or returns error info as JSON object.
+ *
+ * @async
+ * @function fetchMagentrix
+ * @param {Object} opts - Fetch options.
+ * @param {string} opts.instanceUrl - Magentrix instance base URL (e.g. https://your.magentrix.com).
+ * @param {string} [opts.token] - OAuth2 bearer token for authentication (optional for public endpoints).
+ * @param {string} opts.path - API path (e.g. '/api/3.0/entity/activeclass').
+ * @param {string} [opts.method='GET'] - HTTP method.
+ * @param {any} [opts.body] - Request body (object for JSON, or raw for FormData, Blob, string, etc).
+ * @param {Object} [opts.headers] - Additional headers to merge with defaults.
+ * @param {boolean} [opts.returnErrorObject=false] - If true, errors are returned as JSON objects instead of thrown as Error.
+ * @returns {Promise<Object>} Parsed JSON response from the API if successful.
+ * @throws {Error|Object} Throws Error (default) or error object if returnErrorObject is true.
+ */
+export const fetchMagentrix = async ({
+    instanceUrl,
+    token,
+    path,
+    method = 'GET',
+    body,
+    headers = {},
+    ignoreContentType = false,
+    returnErrorObject = false,
+    errorConfig = {
+        includeStatus: false,
+        includeURL: false,
+        label: '', // 'Magentrix errors:',
+        bullets: false
+    },
+}) => {
+    if (!instanceUrl || !path) {
+        const err = { type: 'client', message: 'Missing required parameter(s): instanceUrl or path' };
+        if (returnErrorObject) throw err;
+        throw new Error(err.message);
+    }
+
+    const finalHeaders = {
+        'Accept': 'application/json',
+        ...headers
+    };
+    if (isJsonBody(body)) finalHeaders['Content-Type'] = 'application/json';
+    if (token) finalHeaders['Authorization'] = `Bearer ${token}`;
+    let requestBody;
+    if (body === undefined || body === null) {
+        requestBody = undefined;
+    } else if (isJsonBody(body)) {
+        requestBody = JSON.stringify(body);
+    } else {
+        requestBody = body;
+    }
+    if (!finalHeaders['Content-Type'] && !ignoreContentType) finalHeaders['Content-Type'] = 'application/json';
+
+    let response, responseData;
+    try {
+        response = await fetch(`${instanceUrl.replace(/\/$/, '')}${path}`, {
+            method,
+            headers: finalHeaders,
+            body: requestBody
+        });
+    } catch (err) {
+        const errorObj = {
+            type: 'network',
+            message: `Network error contacting Magentrix API: ${err.message}`,
+            error: err
+        };
+        if (returnErrorObject) throw errorObj;
+        throw new Error(errorObj.message);
+    }
+
+    try {
+        responseData = await response.json();
+    } catch {
+        responseData = null;
+    }
+
+    if (!response.ok) {
+        const errorObj = {
+            type: 'http',
+            status: response.status,
+            statusText: response.statusText,
+            url: response.url,
+            response: responseData,
+        };
+        // Optionally add detailed error message
+        let msg = errorConfig?.includeStatus ? `HTTP ${response.status} ${response.statusText}\n` : '';
+        if (responseData) {
+            const responseErrs = responseData.errors || responseData.Errors;
+
+            if (Array.isArray(responseErrs) && responseErrs.length) {
+                msg += `${errorConfig?.label}${errorConfig?.label ? '\n' : ''}` + responseErrs.map(e => `${errorConfig?.bullets ? " •  " : ""}${e.code ? `[${e.code || '500'}] ` : ''}${e.message || e}`).join('\n');
+            } else if (responseData.message) {
+                msg += `Magentrix message: ${responseData.message}`;
+            } else {
+                msg += JSON.stringify(responseData);
+            }
+        }
+        if (errorConfig?.includeURL) msg += `\nURL: ${response.url}`;
+        errorObj.message = msg;
+        if (returnErrorObject) throw errorObj;
+        throw new Error(msg);
+    }
+
+    // Handle API-level business logic errors
+    if (
+        !responseData ||
+        responseData.success === false ||
+        (Array.isArray(responseData?.errors) && responseData.errors.length > 0) ||
+        responseData.error
+    ) {
+        const errorObj = {
+            type: 'api',
+            url: response.url,
+            response: responseData
+        };
+        let details = '';
+        if (Array.isArray(responseData?.errors) && responseData.errors.length) {
+            details = responseData.errors
+                .map(e => `  • ${e.code ? `[${e.code}] ` : ''}${e.message}`)
+                .join('\n');
+        } else if (responseData?.message) {
+            details = responseData.message;
+        } else if (typeof responseData === 'object') {
+            details = JSON.stringify(responseData);
+        } else {
+            details = String(responseData);
+        }
+        errorObj.message = `Magentrix API error:\n${details}`;
+        if (returnErrorObject) throw errorObj;
+        throw new Error(errorObj.message);
+    }
+
+    return responseData;
+};

package/utils/merge.js

@@ -0,0 +1,22 @@
+import * as diff3 from 'node-diff3';                   // ESM import all
+
+/**
+ * Merges local and remote file contents with a common ancestor (base),
+ * returning the merged result and whether there was a conflict.
+ *
+ * @param {string} baseContent - The last synced (common ancestor) file content.
+ * @param {string} localContent - The current local file content.
+ * @param {string} remoteContent - The remote/server file content.
+ * @returns {{ mergedText: string, hasConflict: boolean }}
+ */
+export function mergeFiles(baseContent, localContent, remoteContent) {
+    const baseLines = baseContent.split('\n');
+    const localLines = localContent.split('\n');
+    const remoteLines = remoteContent.split('\n');
+
+    const result = diff3.merge(localLines, baseLines, remoteLines);
+    const mergedText = result.result.join('\n');
+
+    // Do NOT throw. Just return the merge, which will have conflict markers if unresolved.
+    return mergedText;
+}

package/utils/preferences.js

@@ -0,0 +1,40 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+
+/**
+ * Ensures that the .vscode/settings.json file exists in the project root and
+ * updates it to associate `.xyz` files with C# syntax highlighting in VS Code.
+ * If the file or directory doesn't exist, it will be created. Existing settings
+ * are preserved and merged.
+ *
+ * @async
+ * @function ensureVSCodeFileAssociation
+ * @param {string} projectRoot - The absolute path to the project root where the `.vscode` folder resides.
+ * @returns {Promise<void>} Resolves once the settings file is updated or created.
+ *
+ * @example
+ * await ensureVSCodeFileAssociation(process.cwd());
+ */
+export async function ensureVSCodeFileAssociation(projectRoot) {
+    const vscodeDir = path.join(projectRoot, '.vscode');
+    const settingsPath = path.join(vscodeDir, 'settings.json');
+
+    await fs.mkdir(vscodeDir, { recursive: true });
+
+    let settings = {};
+    try {
+        const raw = await fs.readFile(settingsPath, 'utf-8');
+        settings = JSON.parse(raw);
+    } catch (err) {
+        // Ignore error if file doesn't exist or is invalid JSON
+    }
+
+    settings['files.associations'] = {
+        ...settings['files.associations'],
+        '*.ac': 'csharp',
+        '*.trigger': 'csharp',
+        '*.ctrl': 'csharp'
+    };
+
+    await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
+}

package/utils/spinner.js

@@ -0,0 +1,43 @@
+export async function withSpinner(message, fn, config = { showCompletion: true }) {
+    const spinnerChars = ['|', '/', '-', '\\'];
+    let i = 0;
+    let spinnerActive = true;
+    let spinner;
+
+    // Patch both log and error for full coverage
+    const originalLog = console.log;
+    const originalError = console.error;
+    function clearSpinnerLine() {
+        process.stdout.write('\r' + ' '.repeat(message.length + 8) + '\r');
+        if (spinnerActive) {
+            clearInterval(spinner);
+            spinnerActive = false;
+        }
+    }
+    console.log = (...args) => { clearSpinnerLine(); originalLog(...args); };
+    console.error = (...args) => { clearSpinnerLine(); originalError(...args); };
+
+    process.stdout.write(`${message} `);
+
+    spinner = setInterval(() => {
+        process.stdout.write(`\r${message} ${spinnerChars[i++ % spinnerChars.length]}`);
+    }, 80);
+
+    try {
+        const result = await fn();
+        const treatAsError = result?.hasErrors;
+        spinnerActive = false;
+        clearInterval(spinner);
+        if (config?.showCompletion) process.stdout.write(`\r${message} ${treatAsError ? '❌' : '✅'}\n`);
+        return result;
+    } catch (err) {
+        spinnerActive = false;
+        clearInterval(spinner);
+        if (config?.showCompletion) process.stdout.write(`\r${message} ❌\n`);
+        throw err;
+    } finally {
+        // Restore logs always
+        console.log = originalLog;
+        console.error = originalError;
+    }
+}

package/utils/template.js

@@ -0,0 +1,52 @@
+/**
+ * Returns the default template for an ActiveClass Controller.
+ * @param {string} className
+ * @returns {string}
+ */
+export const getControllerTemplate = (className) => `
+public class ${className} : AspxController {
+    public override ActionResponse Index()
+    {
+        return View();
+    }
+}
+`.trim();
+
+/**
+ * Returns the default template for an ActiveClass Trigger.
+ * @param {string} className - For instance ContactTrigger
+ * @param {string} entityName - For instance Force__Contact
+ * @returns {string}
+ */
+export const getTriggerTemplate = (className, entityName = '<ENTITYNAME>') => `
+public class ${className} : ActiveTrigger<${entityName}>
+{
+    public override void Execute(TransactionContext<${entityName}> trigger) {
+                 
+    }
+}
+`.trim();
+
+/**
+ * Returns the default template for a general ActiveClass.
+ * @param {string} className
+ * @returns {string}
+ */
+export const getClassTemplate = (className) => `
+public class ${className} {
+    
+}
+`.trim();
+
+/**
+ * Returns the default template for an Active Page.
+ * @param {string} pageName
+ * @param {string} pageLabel
+ * @returns {string}
+ */
+export const getPageTemplate = (pageName, pageLabel) => `
+<aspx:AspxPage runat="server" Id="${pageName}" title="${pageLabel}">
+<body>
+</body>
+</aspx:AspxPage>
+`.trim();

package/utils/updateFileBase.js

@@ -0,0 +1,103 @@
+import { EXPORT_ROOT } from "../vars/global.js";
+import fs from "fs";
+import path from "path";
+import { sha256 } from "./hash.js";
+import Config from "./config.js";
+import { compressString } from "./compress.js";
+
+const config = new Config();
+
+/**
+ * Recursively collects all file paths under a directory, returning relative paths from base.
+ *
+ * @param {string} dirPath - Absolute or relative path to the root directory to scan.
+ * @param {string} [basePath=''] - Internal use. The base path for recursion, relative to dirPath.
+ * @returns {string[]} Array of relative file paths found under dirPath.
+ */
+export function getAllFiles(dirPath, basePath = "") {
+    let results = [];
+    const fullDirPath = path.join(dirPath, basePath);
+    const entries = fs.readdirSync(fullDirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+        const relPath = path.join(basePath, entry.name);
+        const entryPath = path.join(dirPath, relPath);
+
+        if (entry.isDirectory()) {
+            // Recurse into subdirectory
+            results = results.concat(getAllFiles(dirPath, relPath));
+        } else if (entry.isFile()) {
+            // Add file's relative path to results
+            results.push(relPath);
+        }
+    }
+    return results;
+}
+
+/**
+ * Updates (or creates) the base sync state for a specific file.
+ *
+ * Saves the current file's lastModified time, content hash, and contents
+ * to base.json using config.save(), under the key of the file's relative path.
+ *
+ * This should be called only when the local and remote file are confirmed to be in sync
+ * (i.e., after a successful pull, push, or conflict resolution).
+ *
+ * @param {string} filePath - The expected path to the file (relative to project root or EXPORT_ROOT).
+ * @param {object} record - The Magentrix record
+ * @param {string} actualPath - Should only be provided if the file has been renamed and the base has not been updated
+ * @param {object} contentSnapshot - Optional { content, hash } snapshot of what was actually published (prevents race conditions)
+ */
+export const updateBase = (filePath, record, actualPath = '', contentSnapshot = null) => {
+    // This is the true location of the file
+    const fileSystemLocation = actualPath || path.resolve(filePath);
+
+    if (!fs.existsSync(fileSystemLocation)) {
+        console.error(`❌ File does not exist: ${filePath}`);
+        return;
+    }
+
+    // Get file stats for mtime
+    const fileStats = fs.statSync(fileSystemLocation);
+
+    // Use snapshot if provided (to avoid race conditions), otherwise read from disk
+    let fileContent, contentHash;
+    if (contentSnapshot && contentSnapshot.content) {
+        // Use the snapshot of what was actually published
+        fileContent = contentSnapshot.content;
+        contentHash = contentSnapshot.hash;
+    } else {
+        // Read from disk (normal behavior)
+        fileContent = fs.readFileSync(fileSystemLocation, "utf-8");
+        contentHash = sha256(fileContent);
+    }
+
+    // Save sync metadata and content to base.json via config manager.
+    // - key: the relative path to the file
+    // - value: lastModified, contentHash, and full content
+    // - options: ensure writing to base.json
+    const saveData = {
+        lastModified: fileStats.mtimeMs,
+        contentHash,
+        compressedContent: compressString(fileContent),
+        recordId: record.Id,
+        type: record.Type,
+        filePath,
+        lastKnownActualPath: fileSystemLocation,
+        lastKnownPath: path.resolve(filePath)
+    }
+
+    if (saveData.type === 'File') delete saveData.compressedContent;
+
+    config.save(
+        record.Id,
+        saveData,
+        {
+            filename: "base.json"
+        }
+    );
+};
+
+export const removeFromBase = (recordId) => {
+    config.removeKey(recordId, { filename: "base.json" });
+}

package/vars/config.js

@@ -0,0 +1 @@
+export const VERSION = '1.0.0'

package/vars/global.js

@@ -0,0 +1,33 @@
+import { sha256 } from '../utils/hash.js'; // Or wherever your hash function lives
+
+export const CWD = process.cwd();
+export const HASHED_CWD = sha256(CWD);
+export const EXPORT_ROOT = "src";
+
+/**
+     * Maps Magentrix Type fields to local folder names and extensions.
+     * Extensions chosen to avoid collisions and clearly indicate type.
+     */
+export const TYPE_DIR_MAP = {
+    Class: { directory: "Classes", extension: "ac" },
+    Trigger: { directory: "Triggers", extension: "trigger" },
+    Controller: { directory: "Controllers", extension: "ctrl" },
+    "Active Page": { directory: "Pages", extension: "aspx" }, // For ActivePage
+    "Active Template": { directory: "Templates", extension: "aspx" }
+};
+
+export const ENTITY_TYPE_MAP = {
+    'Active Page': "ActivePage",
+    "Active Template": "ActivePage",
+    "Class": "ActiveClass",
+    "Controller": "ActiveClass",
+    "Trigger": "ActiveClass"
+}
+
+export const ENTITY_FIELD_MAP = {
+    "Active Page": "Content",
+    "Active Template": "Content",
+    "Class": "Body",
+    "Controller": "Body",
+    "Trigger": "Body",
+}