imcp 0.0.19 → 0.1.2

package/src/core/loaders/InstallOperationManager.ts

@@ -0,0 +1,367 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { SETTINGS_DIR } from '../metadatas/constants.js';
+import { InstallOperationDetails, InstallOperationStep } from '../metadatas/types.js';
+import { Logger } from '../../utils/logger.js';
+
+const INSTALL_STATUS_DIR = path.join(SETTINGS_DIR, 'InstallOperationStatus');
+
+export class InstallOperationManager {
+  private installOperationStatus: Record<string, InstallOperationDetails> = {};
+  private statusLock: Promise<void> = Promise.resolve();
+  private readonly categoryName: string;
+  private readonly serverName: string;
+  private readonly statusFilePath: string;
+
+  /**
+   * Creates an InstallOperationManager instance for a specific category and server.
+   * @param categoryName The name of the category.
+   * @param serverName The name of the server.
+   */
+  constructor(categoryName: string, serverName: string) {
+    this.categoryName = categoryName;
+    this.serverName = serverName;
+    this.statusFilePath = path.join(
+      INSTALL_STATUS_DIR,
+      this.categoryName,
+      `${this.serverName}.json`
+    );
+    this.loadStatuses().catch(error => Logger.error('Failed to initialize InstallOperationManager:', error));
+  }
+
+  /**
+   * Returns an InstallOperationManager instance for the given category and server.
+   * @param categoryName The name of the category.
+   * @param serverName The name of the server.
+   */
+  private static instanceMap: Map<string, InstallOperationManager> = new Map();
+
+  /**
+   * Returns a cached InstallOperationManager instance for the given category and server.
+   * If an instance does not exist, it will be created and cached.
+   * @param categoryName The name of the category.
+   * @param serverName The name of the server.
+   */
+  public static getInstance(categoryName: string, serverName: string): InstallOperationManager {
+    const key = `${categoryName}::${serverName}`;
+    if (!this.instanceMap.has(key)) {
+      this.instanceMap.set(key, new InstallOperationManager(categoryName, serverName));
+    }
+    return this.instanceMap.get(key)!;
+  }
+
+  private async withLock<T>(operation: () => Promise<T>): Promise<T> {
+    const current = this.statusLock;
+    let resolve: () => void;
+    this.statusLock = new Promise<void>(r => resolve = r);
+    try {
+      await current;
+      return await operation();
+    } finally {
+      resolve!();
+    }
+  }
+
+  private async loadStatuses(): Promise<void> {
+    await this.withLock(async () => {
+      try {
+        await fs.mkdir(path.dirname(this.statusFilePath), { recursive: true });
+        const data = await fs.readFile(this.statusFilePath, 'utf-8');
+        this.installOperationStatus = JSON.parse(data);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+          this.installOperationStatus = {};
+          await this.saveStatuses(); // Create the file if it doesn't exist
+        } else {
+          Logger.error('Failed to load install operation statuses:', error);
+          this.installOperationStatus = {}; // Initialize with empty statuses in case of other errors
+        }
+      }
+    });
+  }
+
+  private async saveStatuses(): Promise<void> {
+    await fs.mkdir(path.dirname(this.statusFilePath), { recursive: true });
+    await fs.writeFile(this.statusFilePath, JSON.stringify(this.installOperationStatus, null, 2));
+  }
+
+  private get operationKey(): string {
+    return `${this.categoryName}-${this.serverName}`;
+  }
+
+  /**
+   * Record a step for this category/server instance.
+   */
+  public async recordStep(
+    stepName: string,
+    status: 'pending' | 'in-progress' | 'completed' | 'failed',
+    message?: string
+  ): Promise<InstallOperationDetails> {
+    return await this.withLock(async () => {
+      let operationDetails = this.installOperationStatus[this.operationKey];
+
+      const newStep: InstallOperationStep = {
+        name: stepName,
+        status,
+        message,
+        timestamp: new Date().toISOString(),
+      };
+
+      if (!operationDetails) {
+        operationDetails = {
+          currentStep: stepName,
+          steps: [newStep],
+          lastUpdated: new Date().toISOString(),
+          error: status === 'failed' ? message : undefined,
+          overallStatus: status === 'failed' ? 'failed' : 'in-progress',
+        };
+      } else {
+        // Check for an existing unfinished step with the same name
+        const existingStepIndex = operationDetails.steps.findIndex(
+          s => s.name === stepName && s.status !== 'completed' && s.status !== 'failed'
+        );
+        if (existingStepIndex !== -1) {
+          // Update the existing unfinished step
+          operationDetails.steps[existingStepIndex] = newStep;
+        } else {
+          operationDetails.steps.push(newStep);
+        }
+        operationDetails.currentStep = stepName;
+        operationDetails.lastUpdated = new Date().toISOString();
+
+        if (status === 'failed') {
+          operationDetails.overallStatus = 'failed';
+          if (!operationDetails.error) { // Store the first error
+            operationDetails.error = message;
+          }
+          // Mark all in-progress steps as cancelled
+          operationDetails.steps = operationDetails.steps.map(s =>
+            s.status === 'in-progress'
+              ? {
+                ...s,
+                status: 'canceled',
+                message: (s.message ? s.message + ' ' : '') + '[Canceled due to failure]',
+                timestamp: new Date().toISOString(),
+              }
+              : s
+          );
+        } else if (status === 'completed' && stepName.toLowerCase().includes('completed')) {
+          // Check if all steps are completed or if there are any failures
+          const allStepsCompleted = operationDetails.steps.every(s =>
+            s.status === 'completed' || (s.name === stepName && status === 'completed')
+          );
+          operationDetails.overallStatus = allStepsCompleted ? 'completed' : 'in-progress';
+          if (allStepsCompleted) {
+            operationDetails.error = undefined; // Clear error on completion
+          }
+        } else {
+          if (operationDetails.overallStatus !== 'failed') {
+            operationDetails.overallStatus = 'in-progress';
+          }
+        }
+      }
+
+      // Special handling for the "InstallCompleted" step or similar final step names
+      if (stepName === 'InstallCompleted') {
+        operationDetails.overallStatus = status === 'completed' ? 'completed' : 'failed';
+        if (status === 'completed') operationDetails.error = undefined;
+      }
+
+      this.installOperationStatus[this.operationKey] = operationDetails;
+      await this.saveStatuses();
+      return operationDetails;
+    });
+  }
+
+  /**
+   * Resets (deletes) the operation status for this category/server.
+   * This is useful to call before starting a new installation attempt.
+   */
+  public async resetOperation(): Promise<InstallOperationManager> {
+    await this.withLock(async () => {
+      if (this.installOperationStatus[this.operationKey]) {
+        delete this.installOperationStatus[this.operationKey];
+        Logger.info(`Reset installation operation status for ${this.operationKey}`);
+        await this.saveStatuses();
+      }
+    });
+    return this;
+  }
+
+  /**
+   * Gets the details for this category/server.
+   */
+  public async getDetails(): Promise<InstallOperationDetails | undefined> {
+    await this.loadStatuses(); // Ensure latest statuses are loaded
+    return this.installOperationStatus[this.operationKey];
+  }
+
+  /**
+   * Gets all operation details in this file (for this category/server).
+   */
+  public async getAllDetails(): Promise<Record<string, InstallOperationDetails>> {
+    await this.loadStatuses();
+    return this.installOperationStatus;
+  }
+
+  /**
+   * Explicitly mark the overall status of an operation as 'completed' or 'failed'.
+   * This can be used to force the final state regardless of step details.
+   * @param status 'completed' or 'failed'
+   * @param error Optional error message if failed
+   */
+  public async markOverallStatus(status: 'completed' | 'failed', error?: string): Promise<InstallOperationDetails | undefined> {
+    return await this.withLock(async () => {
+      const operationDetails = this.installOperationStatus[this.operationKey];
+      if (!operationDetails) return undefined;
+      operationDetails.overallStatus = status;
+      operationDetails.lastUpdated = new Date().toISOString();
+      if (status === 'failed') {
+        if (error) {
+          operationDetails.error = error;
+        }
+        // Mark all in-progress steps as cancelled
+        operationDetails.steps = operationDetails.steps.map(s =>
+          s.status === 'in-progress'
+            ? {
+              ...s,
+              status: 'canceled',
+              message: (s.message ? s.message + ' ' : '') + '[Canceled due to failure]',
+              timestamp: new Date().toISOString(),
+            }
+            : s
+        );
+      }
+      if (status === 'completed') {
+        operationDetails.error = undefined;
+      }
+      await this.saveStatuses();
+      return operationDetails;
+    });
+  }
+
+  /**
+   * Executes a function and records its step status as 'in-progress', 'completed', or 'failed'.
+   *
+   * Useful for wrapping tasks with consistent status tracking and flexible error handling.
+   *
+   * @template T The return type of the function being executed.
+   *
+   * @param fn The function to execute. Can be synchronous or asynchronous.
+   * @param options Optional configuration:
+   *  - stepName: Custom name for the step. Defaults to the function name or 'unnamedStep'.
+   *  - inProgressMessage: Optional message to log when the step starts.
+   *  - endMessage: Optional static string or function to generate a final message from the result or error.
+   *  - onResult: A function `(result: T) => boolean` that determines whether the step was successful. Defaults to always `true`.
+   *  - onError: Optional function `(error) => { result: T; message: string } | never` that handles an error and may return a fallback result and message, or throw.
+   *
+   * @returns A promise that resolves with the result of the function if successful, or rethrows on failure.
+   *
+   * @throws The original error or any error thrown from `onError`.
+   */
+  public async recording<T>(
+    fn: () => T | Promise<T>,
+    options?: {
+      stepName?: string;
+      inProgressMessage?: string;
+      endMessage?: string | ((data: T) => string | undefined);
+      onResult?: (result: T) => boolean;
+      onError?: (error: unknown) => { result: T; message: string } | Promise<{ result: T; message: string }> | never;
+    }
+  ): Promise<T> {
+    const { stepName, inProgressMessage = 'Step in progress', endMessage, onResult = () => true, onError } = options || {};
+
+    const resolvedStepName = stepName ?? (fn.name || 'unnamedStep');
+    const getEndMessage = (data: T, fallback: string) =>
+      typeof endMessage === 'function' ? endMessage(data) || 'Step completed' : endMessage ?? fallback;
+
+    await this.recordStep(resolvedStepName, 'in-progress', inProgressMessage);
+
+    try {
+      const result = await Promise.resolve(fn());
+      const isSuccess = onResult(result);
+      await this.recordStep(resolvedStepName, isSuccess ? 'completed' : 'failed', getEndMessage(result, isSuccess ? 'Step completed successfully' : 'Step failed'));
+      return result;
+    } catch (err) {
+      if (!onError) {
+        await this.recordStep(resolvedStepName, 'failed', (err as Error)?.message || String(err));
+        throw err;
+      }
+
+      try {
+        const { result, message } = await onError(err);
+        await this.recordStep(resolvedStepName, 'failed', message);
+        return result;
+      } catch (onErrorThrown) {
+        await this.recordStep(resolvedStepName, 'failed', (onErrorThrown as Error)?.message || String(onErrorThrown));
+        throw onErrorThrown;
+      }
+    }
+  }
+
+
+  /**
+ * Executes an asynchronous "fire-and-forget" task and records its step status as 'in-progress', 'completed', or 'failed'.
+ *
+ * Unlike `recording`, this does not await the result — it runs the task in the background.
+ * Useful for side-effecting operations like updates or notifications where progress should be logged but not block flow.
+ *
+ * @template T The resolved type of the asynchronous task.
+ *
+ * @param fn The async function to execute.
+ * @param options Optional configuration:
+ *  - stepName: Custom name for the step. Defaults to the function name or 'unnamedStep'.
+ *  - inProgressMessage: Message to log when the step starts.
+ *  - endMessage: Static string or function to generate the final message from result or error.
+ *  - onResult: A boolean or function `(result: T) => boolean` to determine if the step is successful.
+ *  - onError: A function `(error) => string` or `Promise<string>` to handle errors and return a message.
+ *             If it throws, the error is rethrown and logged.
+ *  - onComplete: Optional callback to run after completion, regardless of success or failure.
+ *
+ * @returns void
+ */
+  public recordingAsync<T>(fn: () => Promise<T>, options?: {
+    stepName?: string;
+    inProgressMessage?: string;
+    endMessage?: string | ((result: T) => string);
+    onResult?: (result: T) => boolean;
+    onError?: (error: unknown) => string | Promise<string> | never;
+    onComplete?: () => void;
+  }
+  ): void {
+    const {
+      stepName,
+      inProgressMessage = 'Step in progress',
+      endMessage,
+      onResult = () => true,
+      onError,
+      onComplete,
+    } = options || {};
+
+    const resolvedStepName = stepName ?? (fn.name || 'unnamedStep');
+    const getMessage = (data: T, fallback: string) => typeof endMessage === 'function' ? endMessage(data) : endMessage ?? fallback;
+
+    this.recordStep(resolvedStepName, 'in-progress', inProgressMessage).then(() => {
+      fn()
+        .then(result => {
+          const isSuccess = onResult(result);
+          const message = getMessage(result, isSuccess ? 'Step completed successfully' : 'Step failed');
+          this.recordStep(resolvedStepName, isSuccess ? 'completed' : 'failed', message).then(onComplete).catch();
+        })
+        .catch(async (err) => {
+          if (onError) {
+            try {
+              const errorMessage = await onError(err);
+              await this.recordStep(resolvedStepName, 'failed', errorMessage);
+            } catch (onErrorThrown) {
+              await this.recordStep(resolvedStepName, 'failed', (onErrorThrown as Error)?.message || String(onErrorThrown));
+              throw onErrorThrown;
+            }
+          } else {
+            const fallback = getMessage(err, (err as Error)?.message || String(err));
+            await this.recordStep(resolvedStepName, 'failed', fallback);
+          }
+        });
+    });
+  }
+}

package/src/core/loaders/SystemSettingsManager.ts

@@ -0,0 +1,278 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { SETTINGS_DIR } from '../metadatas/constants.js';
+import { SystemSettings } from '../metadatas/types.js';
+import { Logger } from '../../utils/logger.js';
+import { getSystemPythonExecutablePath, getNpmExecutablePath, getBrowserPath } from '../../utils/osUtils.js';
+
+const SETTINGS_FILE_NAME = 'system_settings.json';
+const SETTINGS_FILE_PATH = path.join(SETTINGS_DIR, 'settings', SETTINGS_FILE_NAME);
+
+export class SystemSettingsManager {
+    private static instance: SystemSettingsManager;
+    private settings: SystemSettings;
+    private settingsFilePath: string;
+    private settingsLock: Promise<void> = Promise.resolve();
+
+    private constructor() {
+        this.settingsFilePath = SETTINGS_FILE_PATH;
+        this.settings = {};
+        // No await here, initialization is best-effort. Lock will protect subsequent calls.
+        this.loadSettings().catch(error => {
+            Logger.error('Failed to initialize SystemSettingsManager during construction:', error);
+            // Initialize with empty settings if load fails, defaults will be applied on first access
+            this.settings = {};
+        });
+    }
+
+    public static getInstance(): SystemSettingsManager {
+        if (!SystemSettingsManager.instance) {
+            SystemSettingsManager.instance = new SystemSettingsManager();
+        }
+        return SystemSettingsManager.instance;
+    }
+
+    private async withLock<T>(operation: () => Promise<T>): Promise<T> {
+        const currentLock = this.settingsLock;
+        let releaseLock: () => void;
+        this.settingsLock = new Promise<void>(resolve => releaseLock = resolve);
+        try {
+            await currentLock;
+            return await operation();
+        } finally {
+            releaseLock!();
+        }
+    }
+
+    // Internal method without lock
+    private async _loadSettingsInternal(): Promise<void> {
+        try {
+            await fs.mkdir(path.dirname(this.settingsFilePath), { recursive: true });
+            const data = await fs.readFile(this.settingsFilePath, 'utf-8');
+            this.settings = JSON.parse(data);
+            await this._applyDefaultsIfNeededInternal(); // Call internal version
+        } catch (error) {
+            if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+                Logger.info(`Settings file not found at ${this.settingsFilePath}. Initializing with defaults.`);
+                this.settings = {};
+                await this._applyDefaultsIfNeededInternal(); // Call internal version
+            } else {
+                Logger.error(`Error loading settings from ${this.settingsFilePath}:`, error);
+                this.settings = {};
+                await this._applyDefaultsIfNeededInternal(); // Call internal version
+            }
+        }
+    }
+
+    /**
+     * Loads settings from the file. This operation is atomic.
+     * If the settings file doesn't exist, it initializes with defaults and creates the file.
+     * @returns A promise that resolves when settings are loaded.
+     */
+    public async loadSettings(): Promise<void> {
+        return this.withLock(() => this._loadSettingsInternal());
+    }
+
+    // Internal method without lock
+    private async _applyDefaultsIfNeededInternal(): Promise<void> {
+        let updated = false;
+        const normalizePath = (p?: string) => p ? p.replace(/\\/g, '/') : undefined;
+
+        if (!this.settings.pythonEnvs) {
+            this.settings.pythonEnvs = {};
+            updated = true;
+        }
+
+        if (!this.settings.pythonEnvs["system"]) {
+            try {
+                const pythonPath = normalizePath(await getSystemPythonExecutablePath() || undefined);
+                if (pythonPath) {
+                    this.settings.pythonEnvs["system"] = pythonPath;
+                    updated = true;
+                }
+            } catch (e) {
+                Logger.warn(`Could not get default pythonEnv: ${e}`);
+            }
+        }
+
+        if (!this.settings.nodePath) {
+            try {
+                const npmExecDir = await getNpmExecutablePath();
+                let nodeExecutable = process.platform === 'win32' ? 'node.exe' : 'node';
+                const platformNodePath = process.platform === 'win32'
+                    ? path.join(npmExecDir || '', nodeExecutable)
+                    : path.join(npmExecDir || '', 'bin', nodeExecutable);
+                this.settings.nodePath = npmExecDir ? normalizePath(platformNodePath) : undefined;
+                if (this.settings.nodePath) updated = true;
+            } catch (e) {
+                Logger.warn(`Could not get default nodePath: ${e}`);
+            }
+        } else {
+            this.settings.nodePath = normalizePath(this.settings.nodePath);
+        }
+
+        if (!this.settings.browserPath) {
+            try {
+                this.settings.browserPath = normalizePath(await getBrowserPath() || undefined);
+                if (this.settings.browserPath) updated = true;
+            } catch (e) {
+                Logger.warn(`Could not get default browserPath: ${e}`);
+            }
+        } else {
+            this.settings.browserPath = normalizePath(this.settings.browserPath);
+        }
+
+        if (!this.settings.systemEnvironments) {
+            this.settings.systemEnvironments = { ...process.env } as Record<string, string>;
+            updated = true;
+        }
+        if (this.settings.userConfigurations === undefined) {
+            this.settings.userConfigurations = {};
+            updated = true;
+        }
+
+        if (updated) {
+            await this._saveSettingsInternal();
+        }
+    }
+    
+    /**
+     * Applies default values to settings if they are not already set.
+     * This operation is atomic and saves settings if defaults are applied.
+     * @returns A promise that resolves when defaults are applied and saved if necessary.
+     */
+    public async applyDefaultsIfNeeded(): Promise<void> {
+        return this.withLock(() => this._applyDefaultsIfNeededInternal());
+    }
+
+    /**
+     * Retrieves the current system settings.
+     * If settings haven't been loaded or are empty, it attempts to load them.
+     * Paths within the settings are normalized (e.g., backslashes to forward slashes).
+     * @returns A promise that resolves to the `SystemSettings` object.
+     */
+    public async getSystemSettings(): Promise<SystemSettings> {
+        // Ensure settings are loaded if they are empty.
+        if (Object.keys(this.settings).length === 0) {
+            // Use the public, locked version of loadSettings here
+            await this.loadSettings();
+        }
+        // Return a deep copy to prevent external modification of the internal state.
+        // Ensure this.settings is used, not a potentially stale local copy.
+        const settingsToReturn = JSON.parse(JSON.stringify(this.settings));
+
+        // Ensure paths are normalized when retrieved
+        const normalizedSettings = { ...settingsToReturn };
+
+        // Normalize paths in pythonEnvs
+        if (normalizedSettings.pythonEnvs) {
+            const normalizedPythonEnvs: Record<string, string> = {};
+            Object.keys(normalizedSettings.pythonEnvs).forEach(key => {
+                normalizedPythonEnvs[key] = normalizedSettings.pythonEnvs?.[key]?.replace(/\\/g, '/') || '';
+            });
+            normalizedSettings.pythonEnvs = normalizedPythonEnvs;
+        }
+
+        normalizedSettings.nodePath = normalizedSettings.nodePath?.replace(/\\/g, '/');
+        normalizedSettings.browserPath = normalizedSettings.browserPath?.replace(/\\/g, '/');
+        return normalizedSettings;
+    }
+
+    /**
+     * Creates or updates system settings with the provided partial settings.
+     * This operation is atomic and protected by a lock.
+     * It loads existing settings if not already loaded, merges the new settings,
+     * applies any necessary defaults, and then saves the updated settings.
+     * @param newSettings A `Partial<SystemSettings>` object containing the settings to update.
+     * @returns A promise that resolves to the fully updated and normalized `SystemSettings`.
+     */
+    public async createOrUpdateSystemSettings(newSettings: Partial<SystemSettings>): Promise<SystemSettings> {
+        return this.withLock(async () => {
+            // Ensure current settings are loaded before modification by calling the internal, non-locking version
+            if (Object.keys(this.settings).length === 0) {
+                await this._loadSettingsInternal();
+            }
+
+            const normalizePath = (p?: string) => p ? p.replace(/\\/g, '/') : undefined;
+
+            // Initialize pythonEnvs if it doesn't exist on the current settings
+            if (!this.settings.pythonEnvs) {
+                this.settings.pythonEnvs = {};
+            }
+
+            // Create a new settings object by merging current and new settings.
+            const updatedSettings: SystemSettings = {
+                ...this.settings, // Start with current settings
+                ...newSettings,   // Override with new settings
+                // Explicitly handle potentially undefined paths from newSettings
+                nodePath: normalizePath(newSettings.nodePath !== undefined ? newSettings.nodePath : this.settings.nodePath),
+                browserPath: normalizePath(newSettings.browserPath !== undefined ? newSettings.browserPath : this.settings.browserPath),
+                // Ensure systemEnvironments and userConfigurations are properly merged or taken from newSettings
+                systemEnvironments: newSettings.systemEnvironments !== undefined
+                    ? newSettings.systemEnvironments
+                    : this.settings.systemEnvironments, // Keep existing if not in newSettings
+                userConfigurations: newSettings.userConfigurations !== undefined
+                    ? newSettings.userConfigurations
+                    : this.settings.userConfigurations || {}, // Keep existing or default to empty
+            };
+
+            this.settings = updatedSettings;
+
+            // Call the internal, non-locking version of applyDefaultsIfNeeded
+            await this._applyDefaultsIfNeededInternal();
+            
+            // _applyDefaultsIfNeededInternal will call _saveSettingsInternal if it makes changes.
+            // However, if newSettings were provided that didn't trigger a change in _applyDefaultsIfNeededInternal
+            // (e.g., just updating an existing path), we still need to save.
+            // So, always call _saveSettingsInternal to persist all merged changes.
+            await this._saveSettingsInternal();
+
+            Logger.info('System settings updated.');
+            // getSystemSettings will handle its own locking if it needs to load.
+            return this.getSystemSettings();
+        });
+    }
+
+    /**
+     * Internal method to save settings to the file without acquiring a lock.
+     * Assumes the lock is already held by the calling public method.
+     * Normalizes paths before saving.
+     * @returns A promise that resolves when settings are written to disk.
+     */
+    private async _saveSettingsInternal(): Promise<void> {
+        try {
+            // Normalize paths before saving
+            const settingsToSave = { ...this.settings };
+            settingsToSave.nodePath = settingsToSave.nodePath?.replace(/\\/g, '/');
+            settingsToSave.browserPath = settingsToSave.browserPath?.replace(/\\/g, '/');
+
+            if (settingsToSave.pythonEnvs) {
+                const normalizedPythonEnvs: Record<string, string> = {};
+                Object.keys(settingsToSave.pythonEnvs).forEach(key => {
+                    normalizedPythonEnvs[key] = settingsToSave.pythonEnvs?.[key]?.replace(/\\/g, '/') || '';
+                });
+                settingsToSave.pythonEnvs = normalizedPythonEnvs;
+            }
+
+            await fs.mkdir(path.dirname(this.settingsFilePath), { recursive: true });
+            await fs.writeFile(this.settingsFilePath, JSON.stringify(settingsToSave, null, 2));
+            Logger.info(`System settings saved to ${this.settingsFilePath}`);
+        } catch (error) {
+            Logger.error(`Error saving settings to ${this.settingsFilePath}:`, error);
+            throw error; // Re-throw to indicate failure
+        }
+    }
+
+    /**
+     * Saves the current settings to the file. This operation is atomic and protected by a lock.
+     * Paths are normalized before saving.
+     * @returns A promise that resolves when the settings are saved.
+     */
+    public async saveSettings(): Promise<void> {
+        await this.withLock(async () => {
+            await this._saveSettingsInternal();
+        });
+    }
+}
+
+export const systemSettingsManager = SystemSettingsManager.getInstance();

package/src/core/metadatas/constants.ts

@@ -31,6 +31,15 @@ export const SETTINGS_DIR = (() => {
  * Local feeds directory path
  */
 export const LOCAL_FEEDS_DIR = path.join(SETTINGS_DIR, 'feeds');
+
+/**
+ * Path to the user information file
+ */
+export const USER_INFO_PATH = path.join(SETTINGS_DIR, 'settings', 'user_info.json');
+
+/**
+ * Path to the local feeds schema directory
+ */
 export const LOCAL_FEEDS_SCHEMA_DIR = path.join(LOCAL_FEEDS_DIR, 'schemas');
 
 const CODE_STRORAGE_DIR = (() => {