@magentrix-corp/magentrix-cli 1.0.0

package/utils/compare.js

@@ -0,0 +1,135 @@
+import fs from 'fs';
+import { sha256 } from './hash.js';
+import { findFileByTag } from './filetag.js';
+import path from 'path';
+
+/**
+ * Compares a local file to its remote representation and determines their sync status.
+ *
+ * - Checks file existence, last modified times, and content hashes.
+ * - Returns detailed sync info; never logs or warns directly.
+ *
+ * @param {string} localFilePath - The path to the local file.
+ * @param {Object} remoteData - Object containing remote file metadata and content.
+ * @param {string} remoteData.content - The file content from the remote.
+ * @param {string} remoteData.ModifiedOn - The last modified date of the remote file (ISO string).
+ * @returns {Object} An object describing the sync status. Possible statuses:
+ *   - 'in_sync': Files match (hashes and times).
+ *   - 'behind': Local file is older than remote, but content is identical.
+ *   - 'conflict': Local file is behind remote and contents differ (conflict).
+ *   - 'ahead': Local file is newer than remote and contents differ.
+ *   - 'ahead_identical': Local file is newer than remote but contents are identical (possible clock drift).
+ *   - 'content_differs': Timestamps match but contents differ (possible manual edit).
+ *   - 'missing': Local file does not exist (safe to download from remote).
+ *   Additional returned fields depend on status.
+ */
+export function compareLocalAndRemote(localFilePath, remoteData) {
+    // If local file does not exist, it's fine—just return 'missing'
+    if (!fs.existsSync(localFilePath)) {
+        return {
+            status: 'missing',
+            message: 'Local file is missing.'
+        };
+    }
+
+    // Gather local file details
+    const localStats = fs.statSync(localFilePath);
+    const localContent = fs.readFileSync(localFilePath, 'utf8');
+    const localMtime = Math.ceil(localStats.mtimeMs); // Local last modified time (ms)
+    const localHash = sha256(localContent); // Local file content hash
+
+    // Gather remote file details
+    const remoteContent = remoteData.content;
+    const remoteMtime = Math.ceil(new Date(remoteData.ModifiedOn).getTime()); // Remote last modified time (ms)
+    const remoteHash = sha256(remoteContent); // Remote file content hash
+
+    // Case: local is behind remote (older mtime)
+    if (localMtime < remoteMtime) {
+        if (localHash !== remoteHash) {
+            // File changed on both local and remote: conflict!
+            return {
+                status: 'conflict',
+                localMtime,
+                remoteMtime,
+                localHash,
+                remoteHash,
+                message: 'Local file is behind remote and has conflicting changes.'
+            };
+        } else {
+            // Local is older but identical to remote
+            // return {
+            //     status: 'behind',
+            //     localMtime,
+            //     remoteMtime,
+            //     message: 'Local file is behind remote but contents are identical.'
+            // };
+
+            return {
+                status: 'in_sync',
+                localMtime,
+                remoteMtime,
+                message: 'Local and remote file are in sync.'
+            };
+        }
+    }
+    // Case: local is ahead of remote (newer mtime)
+    else if (localMtime > remoteMtime) {
+        if (localHash !== remoteHash) {
+            return {
+                status: 'ahead',
+                localMtime,
+                remoteMtime,
+                localHash,
+                remoteHash,
+                message: 'Local file is ahead of remote and content differs.'
+            };
+        } else {
+            // Local is ahead but identical
+            // return {
+            //     status: 'ahead_identical',
+            //     localMtime,
+            //     remoteMtime,
+            //     message: 'Local file is ahead of remote but contents are identical.'
+            // };
+
+            return {
+                status: 'in_sync',
+                localMtime,
+                remoteMtime,
+                message: 'Local and remote file are in sync.'
+            };
+        }
+    }
+    // Case: mtimes match
+    else {
+        // Check for rename
+        const matchingFilePath = findFileByTag(remoteData.Id);
+        const absoluteLocalPath = path.resolve(localFilePath);
+
+        if (matchingFilePath !== absoluteLocalPath) {
+            return {
+                status: 'rename',
+                localMtime,
+                remoteMtime,
+                message: 'Local and remote file names differ.'
+            };
+        } else if (localHash === remoteHash) {
+            return {
+                status: 'in_sync',
+                localMtime,
+                remoteMtime,
+                message: 'Local and remote file are in sync.'
+            };
+        } else {
+            // Timestamps match but contents do not
+            return {
+                status: 'content_differs',
+                localMtime,
+                remoteMtime,
+                localHash,
+                remoteHash,
+                message: 'File times match, but content differs (possible manual edit).'
+            };
+        }
+    }
+}

package/utils/compress.js

@@ -0,0 +1,18 @@
+import pako from 'pako';
+
+export const compressString = (input) => {
+    const compressed = pako.deflate(input);
+    const compressedStr = Buffer.from(compressed).toString('base64');
+    return compressedStr;
+}
+
+export const decompressString = (compressedInput) => {
+    try {
+        if (!compressedInput) return '';
+        const decoded = Buffer.from(compressedInput, 'base64');
+        const decompressed = pako.inflate(decoded, { to: 'string' });
+        return decompressed;
+    } catch (err) {
+        return '';
+    }
+}

package/utils/config.js

@@ -0,0 +1,451 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+/**
+ * Config class handles global and per-project configuration.
+ * - Global config: ~/.config/magentrix/config.json (or %APPDATA%\magentrix\config.json on Windows)
+ * - Project config: ./.magentrix/config.json (walks up dirs to support monorepos)
+ * - Secure file/folder permissions (Unix)
+ * - Optionally, global config can be namespaced by pathHash (SHA256 hash of a directory path)
+ * - Supports searching through config data like a database
+ */
+class Config {
+    /**
+     * @param {Object} opts
+     * @param {string} opts.projectDir - Directory to treat as project root (default: process.cwd())
+     * @param {string} opts.projectFolder - Name of per-project config folder (default: '.magentrix')
+     * @param {string} opts.configFile - Config file name (default: 'config.json')
+     * @param {string} opts.globalAppName - Name for global config dir (default: 'magentrix')
+     */
+    constructor({
+        projectDir = process.cwd(),
+        projectFolder = '.magentrix',
+        configFile = 'config.json',
+        globalAppName = 'magentrix',
+    } = {}) {
+        this.projectDir = projectDir;
+        this.projectFolder = projectFolder;
+        this.configFile = configFile;
+        this.globalAppName = globalAppName;
+
+        // File paths for global and project config
+        this.globalConfigPath = this.getGlobalConfigPath();
+        this.projectConfigPath = this.getProjectConfigPath();
+
+        // In-memory cache for config files
+        this._globalConfig = null;
+        this._projectConfig = null;
+    }
+
+    /**
+     * Determine the global config file path:
+     * - Linux/macOS: ~/.config/[app]/config.json
+     * - Windows:     %APPDATA%/[app]/config.json
+     */
+    getGlobalConfigPath() {
+        const base =
+            process.platform === 'win32'
+                ? path.join(process.env.APPDATA, this.globalAppName)
+                : path.join(os.homedir(), '.config', this.globalAppName);
+
+        if (!fs.existsSync(base)) fs.mkdirSync(base, { recursive: true, mode: 0o700 });
+        return path.join(base, this.configFile);
+    }
+
+    /**
+     * Determine the project config file path:
+     * - Walks up from current directory looking for .magentrix/config.json.
+     * - If not found, uses current working directory as default.
+     */
+    getProjectConfigPath() {
+        let dir = this.projectDir;
+        while (dir !== path.dirname(dir)) {
+            const cfgPath = path.join(dir, this.projectFolder, this.configFile);
+            if (fs.existsSync(cfgPath)) return cfgPath;
+            dir = path.dirname(dir);
+        }
+
+        // Fallback: create project config folder in current directory
+        const fallbackDir = path.join(this.projectDir, this.projectFolder);
+        if (!fs.existsSync(fallbackDir)) fs.mkdirSync(fallbackDir, { recursive: true, mode: 0o700 });
+        return path.join(fallbackDir, this.configFile);
+    }
+
+    /**
+     * Internal: Load config JSON from file for project or global config.
+     * @param {'project'|'global'} type
+     * @param {string} [customPath] - Optional custom file path for project loads
+     * @returns {Object} Parsed config, or empty object if missing.
+     */
+    _loadConfig(type = 'project', customPath = null) {
+        const cfgPath = type === 'global'
+            ? this.globalConfigPath
+            : (customPath || this.projectConfigPath);
+
+        try {
+            if (fs.existsSync(cfgPath)) {
+                const data = fs.readFileSync(cfgPath, 'utf8');
+                return JSON.parse(data);
+            }
+        } catch (e) {
+            throw new Error(`Failed to read ${type} config at ${cfgPath}: ${e.message}`);
+        }
+        return {};
+    }
+
+    /**
+     * Internal: Write config JSON to file, using secure file permissions.
+     * @param {Object} obj - The config object to save.
+     * @param {'project'|'global'} type
+     * @param {string} [customPath] - Optional custom file path for project saves
+     */
+    _saveConfig(obj, type = 'project', customPath = null) {
+        const cfgPath = type === 'global'
+            ? this.globalConfigPath
+            : (customPath || this.projectConfigPath);
+
+        const data = JSON.stringify(obj, null, 2);
+        try {
+            fs.writeFileSync(cfgPath, data, { mode: 0o600 });
+        } catch (e) {
+            throw new Error(`Failed to write ${type} config at ${cfgPath}: ${e.message}`);
+        }
+    }
+
+    /**
+     * Read a value from config (global or project).
+     * If opts.pathHash is specified in global mode, data is stored under that subkey.
+     * For project reads, opts.filename can specify a custom filename.
+     * @param {string} [key] - The config key to read. If missing, returns entire config object.
+     * @param {Object} opts
+     * @param {boolean} opts.global - If true, use global config. Otherwise, use project config.
+     * @param {string} [opts.pathHash] - Optional. Hash for namespaced global config.
+     * @param {string} [opts.filename] - Optional. Custom filename for project reads (ignored for global).
+     * @returns {*} The value for the key, or full config object.
+     */
+    read(key, opts = {}) {
+        const isGlobal = opts.global === true;
+        const filename = opts.filename;
+        const pathHash = opts.pathHash;
+
+        if (isGlobal) {
+            if (this._globalConfig === null) this._globalConfig = this._loadConfig('global');
+            if (pathHash) {
+                this._globalConfig[pathHash] = this._globalConfig[pathHash] || {};
+                return key
+                    ? this._globalConfig[pathHash][key]
+                    : { ...this._globalConfig[pathHash] };
+            }
+            return key
+                ? this._globalConfig[key]
+                : { ...this._globalConfig };
+        } else {
+            if (filename) {
+                const projectFolderPath = path.join(this.projectDir, this.projectFolder);
+                const customPath = path.join(projectFolderPath, filename);
+                const customConfig = this._loadConfig('project', customPath);
+                return key
+                    ? customConfig[key]
+                    : { ...customConfig };
+            } else {
+                if (this._projectConfig === null) this._projectConfig = this._loadConfig('project');
+                return key
+                    ? this._projectConfig[key]
+                    : { ...this._projectConfig };
+            }
+        }
+    }
+
+    /**
+ * Remove a key from config (global or project).
+ * If opts.pathHash is specified in global mode, key is removed from that subkey.
+ * For project removals, opts.filename can specify a custom filename.
+ * 
+ * @param {string} key - The config key to remove.
+ * @param {Object} opts
+ * @param {boolean} opts.global - If true, use global config. Otherwise, use project config.
+ * @param {string} [opts.pathHash] - Optional. Hash for namespaced global config.
+ * @param {string} [opts.filename] - Optional. Custom filename for project config.
+ */
+    removeKey(key, opts = {}) {
+        const isGlobal = opts.global === true;
+        const filename = opts.filename;
+        const pathHash = opts.pathHash;
+
+        if (isGlobal) {
+            if (this._globalConfig === null) this._globalConfig = this._loadConfig('global');
+
+            if (pathHash) {
+                if (!this._globalConfig[pathHash]) return;
+                delete this._globalConfig[pathHash][key];
+            } else {
+                delete this._globalConfig[key];
+            }
+
+            this._saveConfig(this._globalConfig, 'global');
+        } else {
+            if (filename) {
+                const projectFolderPath = path.join(this.projectDir, this.projectFolder);
+                if (!fs.existsSync(projectFolderPath)) return;
+                const customPath = path.join(projectFolderPath, filename);
+                const customConfig = this._loadConfig('project', customPath) || {};
+                delete customConfig[key];
+                this._saveConfig(customConfig, 'project', customPath);
+            } else {
+                if (this._projectConfig === null) this._projectConfig = this._loadConfig('project');
+                delete this._projectConfig[key];
+                this._saveConfig(this._projectConfig, 'project');
+            }
+        }
+    }
+
+
+    /**
+     * Save a key-value pair to config (global or project).
+     * If opts.pathHash is specified in global mode, data is stored under that subkey.
+     * For project saves, opts.filename can specify a custom filename.
+     * @param {string} key - The config key.
+     * @param {*} value - The value to store.
+     * @param {Object} opts
+     * @param {boolean} opts.global - If true, use global config. Otherwise, use project config.
+     * @param {string} [opts.pathHash] - Optional. Hash for namespaced global config.
+     * @param {string} [opts.filename] - Optional. Custom filename for project saves (ignored for global).
+     */
+    save(key, value, opts = {}) {
+        const isGlobal = opts.global === true;
+        const filename = opts.filename;
+        const pathHash = opts.pathHash;
+
+        if (isGlobal) {
+            if (this._globalConfig === null) this._globalConfig = this._loadConfig('global');
+            if (pathHash) {
+                this._globalConfig[pathHash] = this._globalConfig[pathHash] || {};
+                this._globalConfig[pathHash][key] = value;
+            } else {
+                this._globalConfig[key] = value;
+            }
+            this._saveConfig(this._globalConfig, 'global');
+        } else {
+            if (filename) {
+                // Ensure project config folder exists
+                const projectFolderPath = path.join(this.projectDir, this.projectFolder);
+                if (!fs.existsSync(projectFolderPath)) {
+                    fs.mkdirSync(projectFolderPath, { recursive: true, mode: 0o700 });
+                }
+                const customPath = path.join(projectFolderPath, filename);
+                // Load, update, and save the custom config file independently
+                const customConfig = this._loadConfig('project', customPath) || {};
+                customConfig[key] = value;
+                this._saveConfig(customConfig, 'project', customPath);
+            } else {
+                // Default project config
+                if (this._projectConfig === null) this._projectConfig = this._loadConfig('project');
+                this._projectConfig[key] = value;
+                this._saveConfig(this._projectConfig, 'project');
+            }
+        }
+    }
+
+    /**
+     * Internal: Deep search through nested objects and arrays
+     * @param {*} obj - The object/value to search through
+     * @param {Object} query - The query object with key-value pairs to match
+     * @param {Object} [options={}] - Search options
+     * @param {boolean} [options.exact=true] - Whether to use exact matching or partial matching
+     * @param {boolean} [options.caseSensitive=true] - Whether string comparisons should be case sensitive
+     * @returns {boolean} True if the object matches the query
+     */
+    _matchesQuery(obj, query, options = {}) {
+        const { exact = true, caseSensitive = true } = options;
+        if (obj === null || obj === undefined) return false;
+        for (const [queryKey, expectedValue] of Object.entries(query)) {
+            if (!this._hasMatchingValue(obj, queryKey, expectedValue, options)) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    /**
+     * Internal: Check if an object has a matching value for a given key (supports nested keys)
+     * @param {*} obj - The object to search in
+     * @param {string} key - The key to search for (supports dot notation for nested keys)
+     * @param {*} expectedValue - The expected value
+     * @param {Object} options - Search options
+     * @returns {boolean} True if a matching value is found
+     */
+    _hasMatchingValue(obj, key, expectedValue, options) {
+        const { exact, caseSensitive } = options;
+        const keys = key.split('.');
+        let current = obj;
+
+        for (const k of keys) {
+            if (current === null || current === undefined) return false;
+
+            if (Array.isArray(current)) {
+                return current.some(item =>
+                    this._hasMatchingValue(item, keys.slice(keys.indexOf(k)).join('.'), expectedValue, options)
+                );
+            } else if (typeof current === 'object') {
+                current = current[k];
+            } else {
+                return false;
+            }
+        }
+
+        return this._compareValues(current, expectedValue, options);
+    }
+
+    /**
+     * Internal: Compare two values based on search options
+     * @param {*} actual - The actual value from the object
+     * @param {*} expected - The expected value from the query
+     * @param {Object} options - Comparison options
+     * @returns {boolean} True if values match according to options
+     */
+    _compareValues(actual, expected, options) {
+        const { exact, caseSensitive } = options;
+        if (exact) {
+            if (
+                typeof actual === 'string' &&
+                typeof expected === 'string' &&
+                !caseSensitive
+            ) {
+                return actual.toLowerCase() === expected.toLowerCase();
+            }
+            return actual === expected;
+        }
+
+        // Partial matching for strings
+        if (
+            typeof actual === 'string' &&
+            typeof expected === 'string'
+        ) {
+            const a = caseSensitive ? actual : actual.toLowerCase();
+            const e = caseSensitive ? expected : expected.toLowerCase();
+            return a.includes(e);
+        }
+
+        return actual === expected;
+    }
+
+    /**
+     * Search through config data like a database query.
+     * Supports nested object searching and various matching options.
+     *
+     * @param {Object} query - Query object with key-value pairs to match
+     * @param {Object} [opts={}] - Search options
+     * @param {boolean} [opts.global=false] - Search in global config if true, project config if false
+     * @param {string} [opts.filename] - Custom filename for project searches
+     * @param {string} [opts.pathHash] - Hash for namespaced global config searches
+     * @param {boolean} [opts.exact=true] - Use exact matching (false for partial string matching)
+     * @param {boolean} [opts.caseSensitive=true] - Case sensitive string comparisons
+     * @param {string} [opts.searchIn] - Specific top-level key to search within (optional)
+     *
+     * @returns {Array} Array of matching objects/values with their keys
+     */
+    searchObject(query, opts = {}) {
+        const {
+            global = false,
+            filename,
+            pathHash,
+            exact = true,
+            caseSensitive = true,
+            searchIn,
+        } = opts;
+
+        let configData = global
+            ? this.read(null, { global: true, pathHash })
+            : this.read(null, { global: false, filename });
+
+        if (searchIn && configData[searchIn]) {
+            configData = { [searchIn]: configData[searchIn] };
+        }
+
+        const results = [];
+        const recurse = (obj, keyPath = '') => {
+            if (obj === null || obj === undefined) return;
+            if (typeof obj === 'object' && this._matchesQuery(obj, query, { exact, caseSensitive })) {
+                results.push({ key: keyPath, value: obj, matches: query });
+            }
+            if (typeof obj === 'object') {
+                if (Array.isArray(obj)) {
+                    obj.forEach((item, idx) => recurse(item, `${keyPath}[${idx}]`));
+                } else {
+                    Object.entries(obj).forEach(([k, v]) =>
+                        recurse(v, keyPath ? `${keyPath}.${k}` : k)
+                    );
+                }
+            }
+        };
+        recurse(configData);
+        return results;
+    }
+
+    /**
+     * Convenience method for simple key-value searches
+     * @param {string} key - The key to search for
+     * @param {*} value - The value to match
+     * @param {Object} [opts={}] - Same options as searchObject
+     * @returns {Array} Array of matching results
+     */
+    findByKeyValue(key, value, opts = {}) {
+        return this.searchObject({ [key]: value }, opts);
+    }
+
+    /**
+     * Search for objects containing any of the specified values
+     * @param {Object} query - Query object with key-value pairs (OR logic)
+     * @param {Object} [opts={}] - Same options as searchObject
+     * @returns {Array} Array of matching results
+     */
+    searchObjectAny(query, opts = {}) {
+        const {
+            global = false,
+            filename,
+            pathHash,
+            exact = true,
+            caseSensitive = true,
+            searchIn,
+        } = opts;
+
+        let configData = global
+            ? this.read(null, { global: true, pathHash })
+            : this.read(null, { global: false, filename });
+
+        if (searchIn && configData[searchIn]) {
+            configData = { [searchIn]: configData[searchIn] };
+        }
+
+        const results = [];
+        const recurseAny = (obj, keyPath = '') => {
+            if (obj === null || obj === undefined) return;
+            if (typeof obj === 'object') {
+                const matched = Object.entries(query).filter(([qk, qv]) =>
+                    this._hasMatchingValue(obj, qk, qv, { exact, caseSensitive })
+                );
+                if (matched.length) {
+                    results.push({
+                        key: keyPath,
+                        value: obj,
+                        matches: Object.fromEntries(matched),
+                    });
+                }
+            }
+            if (typeof obj === 'object') {
+                if (Array.isArray(obj)) {
+                    obj.forEach((item, idx) => recurseAny(item, `${keyPath}[${idx}]`));
+                } else {
+                    Object.entries(obj).forEach(([k, v]) =>
+                        recurseAny(v, keyPath ? `${keyPath}.${k}` : k)
+                    );
+                }
+            }
+        };
+        recurseAny(configData);
+        return results;
+    }
+}
+
+export default Config;

package/utils/diff.js

@@ -0,0 +1,49 @@
+import { execSync, spawn } from 'child_process';
+import chalk from 'chalk';
+
+/**
+ * Checks if VS Code is installed and accessible via the CLI (`code` command).
+ * @returns {boolean} True if VS Code is available in PATH, false otherwise.
+ */
+export const canOpenDiffInVSCode = () => {
+    try {
+        execSync('code --version', { stdio: 'ignore' });
+        return true;
+    } catch (err) {
+        return false;
+    }
+};
+
+/**
+ * Opens a side-by-side diff of two files in VS Code, if available.
+ * Falls back to terminal diff if VS Code is unavailable.
+ * @param {string} file1 - Path to the first file.
+ * @param {string} file2 - Path to the second file.
+ * @returns {boolean} True if VS Code diff was opened, false if fallback used.
+ */
+export const openDiffInVSCode = (file1, file2) => {
+    if (!canOpenDiffInVSCode()) {
+        console.log(
+            chalk.yellow(
+                'Warning: VS Code is not installed or the `code` command is not in your PATH.\n' +
+                'Falling back to terminal diff.\nSee: https://code.visualstudio.com/docs/setup/mac#_launching-from-the-command-line'
+            )
+        );
+        // Fallback: Use built-in diff (Unix) or fc (Windows)
+        try {
+            if (process.platform === 'win32') {
+                execSync(`fc "${file1}" "${file2}"`, { stdio: 'inherit' });
+            } else {
+                execSync(`diff -u "${file1}" "${file2}"`, { stdio: 'inherit' });
+            }
+        } catch (e) {
+            // Optionally handle diff exit code (e.g., files differ)
+        }
+        return false;
+    }
+
+    const child = spawn('code', ['--diff', file1, file2], { stdio: 'inherit', shell: true });
+    console.log(chalk.green('Opening diff in VS Code...'));
+    
+    return true;
+};