@magentrix-corp/magentrix-cli 1.3.16 → 1.3.17

package/utils/config.js

@@ -1,527 +1,527 @@
-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');
-            }
-        }
-    }
-
-    /**
-     * Remove multiple keys from config (global or project) in a single save operation.
-     * 
-     * @param {string[]} keys - Array of keys 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.
-     */
-    removeKeys(keys, opts = {}) {
-        const isGlobal = opts.global === true;
-        const filename = opts.filename;
-        const pathHash = opts.pathHash;
-
-        if (!Array.isArray(keys) || keys.length === 0) return;
-
-        if (isGlobal) {
-            if (this._globalConfig === null) this._globalConfig = this._loadConfig('global');
-
-            let changed = false;
-            if (pathHash) {
-                if (!this._globalConfig[pathHash]) return;
-                for (const key of keys) {
-                    if (key in this._globalConfig[pathHash]) {
-                        delete this._globalConfig[pathHash][key];
-                        changed = true;
-                    }
-                }
-            } else {
-                for (const key of keys) {
-                    if (key in this._globalConfig) {
-                        delete this._globalConfig[key];
-                        changed = true;
-                    }
-                }
-            }
-
-            if (changed) {
-                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) || {};
-                
-                let changed = false;
-                for (const key of keys) {
-                    if (key in customConfig) {
-                        delete customConfig[key];
-                        changed = true;
-                    }
-                }
-
-                if (changed) {
-                    this._saveConfig(customConfig, 'project', customPath);
-                }
-            } else {
-                if (this._projectConfig === null) this._projectConfig = this._loadConfig('project');
-                
-                let changed = false;
-                for (const key of keys) {
-                    if (key in this._projectConfig) {
-                        delete this._projectConfig[key];
-                        changed = true;
-                    }
-                }
-
-                if (changed) {
-                    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;
+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');
+            }
+        }
+    }
+
+    /**
+     * Remove multiple keys from config (global or project) in a single save operation.
+     * 
+     * @param {string[]} keys - Array of keys 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.
+     */
+    removeKeys(keys, opts = {}) {
+        const isGlobal = opts.global === true;
+        const filename = opts.filename;
+        const pathHash = opts.pathHash;
+
+        if (!Array.isArray(keys) || keys.length === 0) return;
+
+        if (isGlobal) {
+            if (this._globalConfig === null) this._globalConfig = this._loadConfig('global');
+
+            let changed = false;
+            if (pathHash) {
+                if (!this._globalConfig[pathHash]) return;
+                for (const key of keys) {
+                    if (key in this._globalConfig[pathHash]) {
+                        delete this._globalConfig[pathHash][key];
+                        changed = true;
+                    }
+                }
+            } else {
+                for (const key of keys) {
+                    if (key in this._globalConfig) {
+                        delete this._globalConfig[key];
+                        changed = true;
+                    }
+                }
+            }
+
+            if (changed) {
+                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) || {};
+                
+                let changed = false;
+                for (const key of keys) {
+                    if (key in customConfig) {
+                        delete customConfig[key];
+                        changed = true;
+                    }
+                }
+
+                if (changed) {
+                    this._saveConfig(customConfig, 'project', customPath);
+                }
+            } else {
+                if (this._projectConfig === null) this._projectConfig = this._loadConfig('project');
+                
+                let changed = false;
+                for (const key of keys) {
+                    if (key in this._projectConfig) {
+                        delete this._projectConfig[key];
+                        changed = true;
+                    }
+                }
+
+                if (changed) {
+                    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;