imcp 0.0.19 → 0.1.2

package/dist/core/loaders/InstallOperationManager.d.ts

@@ -0,0 +1,115 @@
+import { InstallOperationDetails } from '../metadatas/types.js';
+export declare class InstallOperationManager {
+    private installOperationStatus;
+    private statusLock;
+    private readonly categoryName;
+    private readonly serverName;
+    private readonly statusFilePath;
+    /**
+     * 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);
+    /**
+     * 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;
+    /**
+     * 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.
+     */
+    static getInstance(categoryName: string, serverName: string): InstallOperationManager;
+    private withLock;
+    private loadStatuses;
+    private saveStatuses;
+    private get operationKey();
+    /**
+     * Record a step for this category/server instance.
+     */
+    recordStep(stepName: string, status: 'pending' | 'in-progress' | 'completed' | 'failed', message?: string): Promise<InstallOperationDetails>;
+    /**
+     * Resets (deletes) the operation status for this category/server.
+     * This is useful to call before starting a new installation attempt.
+     */
+    resetOperation(): Promise<InstallOperationManager>;
+    /**
+     * Gets the details for this category/server.
+     */
+    getDetails(): Promise<InstallOperationDetails | undefined>;
+    /**
+     * Gets all operation details in this file (for this category/server).
+     */
+    getAllDetails(): Promise<Record<string, InstallOperationDetails>>;
+    /**
+     * 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
+     */
+    markOverallStatus(status: 'completed' | 'failed', error?: string): Promise<InstallOperationDetails | undefined>;
+    /**
+     * 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`.
+     */
+    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>;
+    /**
+   * 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
+   */
+    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;
+}

package/dist/core/loaders/InstallOperationManager.js

@@ -0,0 +1,311 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { SETTINGS_DIR } from '../metadatas/constants.js';
+import { Logger } from '../../utils/logger.js';
+const INSTALL_STATUS_DIR = path.join(SETTINGS_DIR, 'InstallOperationStatus');
+export class InstallOperationManager {
+    installOperationStatus = {};
+    statusLock = Promise.resolve();
+    categoryName;
+    serverName;
+    statusFilePath;
+    /**
+     * 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, serverName) {
+        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.
+     */
+    static instanceMap = 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.
+     */
+    static getInstance(categoryName, serverName) {
+        const key = `${categoryName}::${serverName}`;
+        if (!this.instanceMap.has(key)) {
+            this.instanceMap.set(key, new InstallOperationManager(categoryName, serverName));
+        }
+        return this.instanceMap.get(key);
+    }
+    async withLock(operation) {
+        const current = this.statusLock;
+        let resolve;
+        this.statusLock = new Promise(r => resolve = r);
+        try {
+            await current;
+            return await operation();
+        }
+        finally {
+            resolve();
+        }
+    }
+    async loadStatuses() {
+        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.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
+                }
+            }
+        });
+    }
+    async saveStatuses() {
+        await fs.mkdir(path.dirname(this.statusFilePath), { recursive: true });
+        await fs.writeFile(this.statusFilePath, JSON.stringify(this.installOperationStatus, null, 2));
+    }
+    get operationKey() {
+        return `${this.categoryName}-${this.serverName}`;
+    }
+    /**
+     * Record a step for this category/server instance.
+     */
+    async recordStep(stepName, status, message) {
+        return await this.withLock(async () => {
+            let operationDetails = this.installOperationStatus[this.operationKey];
+            const newStep = {
+                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.
+     */
+    async resetOperation() {
+        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.
+     */
+    async getDetails() {
+        await this.loadStatuses(); // Ensure latest statuses are loaded
+        return this.installOperationStatus[this.operationKey];
+    }
+    /**
+     * Gets all operation details in this file (for this category/server).
+     */
+    async getAllDetails() {
+        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
+     */
+    async markOverallStatus(status, error) {
+        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`.
+     */
+    async recording(fn, options) {
+        const { stepName, inProgressMessage = 'Step in progress', endMessage, onResult = () => true, onError } = options || {};
+        const resolvedStepName = stepName ?? (fn.name || 'unnamedStep');
+        const getEndMessage = (data, fallback) => 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?.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?.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
+   */
+    recordingAsync(fn, options) {
+        const { stepName, inProgressMessage = 'Step in progress', endMessage, onResult = () => true, onError, onComplete, } = options || {};
+        const resolvedStepName = stepName ?? (fn.name || 'unnamedStep');
+        const getMessage = (data, fallback) => 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?.message || String(onErrorThrown));
+                        throw onErrorThrown;
+                    }
+                }
+                else {
+                    const fallback = getMessage(err, err?.message || String(err));
+                    await this.recordStep(resolvedStepName, 'failed', fallback);
+                }
+            });
+        });
+    }
+}
+//# sourceMappingURL=InstallOperationManager.js.map

package/dist/core/loaders/SystemSettingsManager.d.ts

@@ -0,0 +1,54 @@
+import { SystemSettings } from '../metadatas/types.js';
+export declare class SystemSettingsManager {
+    private static instance;
+    private settings;
+    private settingsFilePath;
+    private settingsLock;
+    private constructor();
+    static getInstance(): SystemSettingsManager;
+    private withLock;
+    private _loadSettingsInternal;
+    /**
+     * 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.
+     */
+    loadSettings(): Promise<void>;
+    private _applyDefaultsIfNeededInternal;
+    /**
+     * 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.
+     */
+    applyDefaultsIfNeeded(): Promise<void>;
+    /**
+     * 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.
+     */
+    getSystemSettings(): Promise<SystemSettings>;
+    /**
+     * 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`.
+     */
+    createOrUpdateSystemSettings(newSettings: Partial<SystemSettings>): Promise<SystemSettings>;
+    /**
+     * 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 _saveSettingsInternal;
+    /**
+     * 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.
+     */
+    saveSettings(): Promise<void>;
+}
+export declare const systemSettingsManager: SystemSettingsManager;