imcp 0.1.1 → 0.1.2

package/dist/core/installers/requirements/GeneralInstaller.js

@@ -1,6 +1,7 @@
 import { BaseInstaller } from './BaseInstaller.js';
 import { handleGitHubRelease } from '../../../utils/githubUtils.js';
 import { handleArtifact } from '../../../utils/adoUtils.js';
+import * as RecordingConstants from '../../metadatas/recordingConstants.js';
 /**
  * Installer implementation for general requirements (type 'other')
  * This installer handles requirements that don't fit into specific package manager categories
@@ -50,8 +51,17 @@ export class GeneralInstaller extends BaseInstaller {
      * @param requirement The requirement to install
      * @returns The status of the installation, including the install path in updateInfo
      */
-    async install(requirement) {
-        try {
+    /**
+     * Install the general requirement
+     * For type 'other', this doesn't actually install anything, but downloads
+     * or locates the asset and returns the path for the caller to use
+     * @param requirement The requirement to install
+     * @param options Optional install options
+     * @param recorder Optional InstallOperationManager for recording steps
+     * @returns The status of the installation, including the install path in updateInfo
+     */
+    async install(requirement, recorder, options) {
+        const doInstall = async () => {
             // For type 'other', a registry must be specified
             if (!requirement.registry) {
                 throw new Error('Registry must be specified for requirement type "other"');
@@ -76,15 +86,41 @@ export class GeneralInstaller extends BaseInstaller {
                 version: requirement.version,
                 inProgress: false,
             };
+        };
+        if (recorder) {
+            return recorder.recording(doInstall, {
+                stepName: RecordingConstants.STEP_GENERAL_INSTALLER_INSTALL,
+                inProgressMessage: `Installing general requirement: ${requirement.name}`,
+                endMessage: (result) => result.installed
+                    ? `Install completed for ${requirement.name}`
+                    : `Install failed for ${requirement.name}`,
+                onError: (error) => {
+                    return {
+                        result: {
+                            name: requirement.name,
+                            type: 'other',
+                            installed: false,
+                            error: error instanceof Error ? error.message : String(error),
+                            inProgress: false,
+                        },
+                        message: error instanceof Error ? error.message : String(error),
+                    };
+                },
+            });
         }
-        catch (error) {
-            return {
-                name: requirement.name,
-                type: 'other',
-                installed: false,
-                error: error instanceof Error ? error.message : String(error),
-                inProgress: false
-            };
+        else {
+            try {
+                return await doInstall();
+            }
+            catch (error) {
+                return {
+                    name: requirement.name,
+                    type: 'other',
+                    installed: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    inProgress: false,
+                };
+            }
         }
     }
 }

package/dist/core/installers/requirements/InstallerFactory.d.ts

@@ -1,6 +1,7 @@
 import { RequirementConfig, RequirementStatus, ServerInstallOptions } from '../../metadatas/types.js';
 import { RequirementInstaller } from './RequirementInstaller.js';
 import { exec } from 'child_process';
+import { InstallOperationManager } from '../../loaders/InstallOperationManager.js';
 /**
  * Factory for creating the appropriate installer for a requirement
  */
@@ -34,10 +35,11 @@ export declare class InstallerFactory {
     /**
      * Install a requirement using the appropriate installer
      * @param requirement The requirement to install
+     * @param recorder Optional InstallOperationManager for recording steps
      * @param options Installation options including python environment
      * @returns The installation status
      */
-    install(requirement: RequirementConfig, options?: ServerInstallOptions): Promise<RequirementStatus>;
+    install(requirement: RequirementConfig, recorder: InstallOperationManager, options?: ServerInstallOptions): Promise<RequirementStatus>;
     /**
       * Check the installation status of a requirement
       * @param requirement The requirement to check

package/dist/core/installers/requirements/InstallerFactory.js

@@ -50,10 +50,11 @@ export class InstallerFactory {
     /**
      * Install a requirement using the appropriate installer
      * @param requirement The requirement to install
+     * @param recorder Optional InstallOperationManager for recording steps
      * @param options Installation options including python environment
      * @returns The installation status
      */
-    async install(requirement, options) {
+    async install(requirement, recorder, options) {
         const installer = this.getInstaller(requirement);
         if (!installer) {
             return {
@@ -64,7 +65,7 @@ export class InstallerFactory {
                 inProgress: false
             };
         }
-        return await installer.install(requirement, options);
+        return await installer.install(requirement, recorder, options);
     }
     /**
       * Check the installation status of a requirement

package/dist/core/installers/requirements/NpmInstaller.d.ts

@@ -1,5 +1,6 @@
 import { RequirementConfig, RequirementStatus, ServerInstallOptions } from '../../metadatas/types.js';
 import { BaseInstaller } from './BaseInstaller.js';
+import { InstallOperationManager } from '../../loaders/InstallOperationManager.js';
 /**
  * Installer implementation for NPM packages
  */
@@ -58,8 +59,9 @@ export declare class NpmInstaller extends BaseInstaller {
     /**
      * Install the NPM package.
      * @param requirement The requirement to install.
-     * @param options Installation options, including pythonCommand for ADO (though not used by npm) and folderName.
+     * @param recorder Optional InstallOperationManager for recording steps.
+     * @param options Installation options.
      * @returns The status of the installation.
      */
-    install(requirement: RequirementConfig, options?: ServerInstallOptions): Promise<RequirementStatus>;
+    install(requirement: RequirementConfig, recorder: InstallOperationManager, options?: ServerInstallOptions): Promise<RequirementStatus>;
 }

package/dist/core/installers/requirements/NpmInstaller.js

@@ -7,6 +7,7 @@ import path from 'path';
 import fs from 'fs/promises';
 import { SETTINGS_DIR } from '../../metadatas/constants.js'; // Corrected path
 import { Logger } from '../../../utils/logger.js';
+import * as RecordingConstants from '../../metadatas/recordingConstants.js';
 /**
  * Installer implementation for NPM packages
  */
@@ -136,13 +137,13 @@ export class NpmInstaller extends BaseInstaller {
      * @param targetDir Target directory for installation.
      * @returns The installed version of the package.
      */
-    async _installPackage(requirement, packageSource, targetDir) {
+    async _installPackage(requirement, packageSource, targetDir, recorder) {
         Logger.debug(`Installing NPM package from "${packageSource}" into "${targetDir}"`);
         await fs.mkdir(targetDir, { recursive: true });
         const installCommand = `npm install ${packageSource} --prefix "${targetDir}"`;
         Logger.debug(`Executing install command: ${installCommand}`);
         const requirementName = this._getRequirementName(requirement);
-        try {
+        return await recorder.recording(async () => {
             const { stdout: installStdout, stderr: installStderr } = await this.execPromise(installCommand);
             Logger.debug(`NPM install stdout for ${packageSource} in ${targetDir}: ${installStdout}`);
             if (installStderr && !installStderr.toLowerCase().includes('added') && !installStderr.toLowerCase().includes('updated') && !installStderr.toLowerCase().includes('found 0 vulnerabilities')) {
@@ -155,24 +156,28 @@ export class NpmInstaller extends BaseInstaller {
                 return { version: installedVersion };
             }
             else {
-                throw new Error(`Successfully ran npm install for ${packageSource}, but ${requirement.name} version could not be determined via npm list in ${targetDir}.`);
+                throw new Error(`Successfully ran npm install for ${packageSource}, but ${requirement.name} version could not be determined via npm list in ${targetDir}, stderr: ${installStderr}`);
             }
-        }
-        catch (error) {
-            Logger.error(`Failed to install or verify NPM package ${packageSource} into ${targetDir}`, error);
-            throw error;
-        }
+        }, {
+            stepName: RecordingConstants.STEP_INSTALLATION_COMMAND_EXECUTION,
+            inProgressMessage: `Running: ${installCommand}`,
+            onError: (error) => {
+                Logger.error(`Error during NPM installation: ${error instanceof Error ? error.message : String(error)}`);
+                throw error;
+            }
+        });
     }
     /**
      * Install the NPM package.
      * @param requirement The requirement to install.
-     * @param options Installation options, including pythonCommand for ADO (though not used by npm) and folderName.
+     * @param recorder Optional InstallOperationManager for recording steps.
+     * @param options Installation options.
      * @returns The status of the installation.
      */
-    async install(requirement, options) {
+    async install(requirement, recorder, options) {
         const targetDir = options?.settings?.folderName || this._getRequirementFolderPath(requirement);
         await fs.mkdir(targetDir, { recursive: true });
-        try {
+        return recorder.recording(async () => {
             const status = await this.checkInstallation(requirement, { settings: { folderName: targetDir } });
             if (status.installed && status.version && compareVersions(status.version, requirement.version) === 0 && !requirement.version.toLowerCase().includes('latest')) {
                 Logger.log(`${requirement.name}@${status.version} already installed in ${targetDir}.`);
@@ -192,10 +197,12 @@ export class NpmInstaller extends BaseInstaller {
                     resolvedVersion = adoResult.version;
                 }
                 else {
+                    if (recorder)
+                        await recorder.recordStep('NpmInstaller:RegistryConfig', 'failed', 'Invalid registry configuration for npm.');
                     throw new Error('Invalid registry configuration for npm.');
                 }
             }
-            const finalInstallResult = await this._installPackage(requirement, packageToInstall, targetDir);
+            const finalInstallResult = await this._installPackage(requirement, packageToInstall, targetDir, recorder);
             resolvedVersion = finalInstallResult.version;
             return {
                 name: requirement.name,
@@ -205,16 +212,25 @@ export class NpmInstaller extends BaseInstaller {
                 inProgress: false,
                 npmPath: targetDir
             };
-        }
-        catch (error) {
-            return {
-                name: requirement.name,
-                type: 'npm',
-                installed: false,
-                error: error instanceof Error ? error.message : String(error),
-                inProgress: false
-            };
-        }
+        }, {
+            stepName: RecordingConstants.STEP_NPM_INSTALLER_INSTALL,
+            inProgressMessage: `Installing npm package: ${requirement.name}`,
+            endMessage: (result) => result.installed
+                ? `Install completed for ${requirement.name}`
+                : `Install failed for ${requirement.name}`,
+            onError: (error) => {
+                return {
+                    result: {
+                        name: requirement.name,
+                        type: 'npm',
+                        installed: false,
+                        error: error instanceof Error ? error.message : String(error),
+                        inProgress: false
+                    },
+                    message: error instanceof Error ? error.message : String(error),
+                };
+            },
+        });
     }
 }
 //# sourceMappingURL=NpmInstaller.js.map

package/dist/core/installers/requirements/PipInstaller.d.ts

@@ -1,5 +1,6 @@
 import { RequirementConfig, RequirementStatus, ServerInstallOptions } from '../../metadatas/types.js';
 import { BaseInstaller } from './BaseInstaller.js';
+import { InstallOperationManager } from '../../loaders/InstallOperationManager.js';
 /**
  * Installer implementation for Python packages using pip
  */
@@ -30,8 +31,9 @@ export declare class PipInstaller extends BaseInstaller {
     /**
      * Install the Python package
      * @param requirement The requirement to install
+     * @param recorder Optional InstallOperationManager for recording steps
      * @param options Optional server install options
      * @returns The status of the installation
      */
-    install(requirement: RequirementConfig, options?: ServerInstallOptions): Promise<RequirementStatus>;
+    install(requirement: RequirementConfig, recorder: InstallOperationManager, options?: ServerInstallOptions): Promise<RequirementStatus>;
 }

package/dist/core/installers/requirements/PipInstaller.js

@@ -1,9 +1,9 @@
 import { BaseInstaller } from './BaseInstaller.js';
 import { handleGitHubRelease, getGitHubLatestVersion } from '../../../utils/githubUtils.js';
-// Assuming getArtifactLatestVersion will be available in adoUtils.ts
 import { handleArtifact as handleAdoArtifact, getArtifactLatestVersion } from '../../../utils/adoUtils.js';
 import { compareVersions } from '../../../utils/versionUtils.js';
 import { Logger } from '../../../utils/logger.js';
+import * as RecordingConstants from '../../metadatas/recordingConstants.js';
 /**
  * Installer implementation for Python packages using pip
  */
@@ -105,21 +105,25 @@ export class PipInstaller extends BaseInstaller {
     /**
      * Install the Python package
      * @param requirement The requirement to install
+     * @param recorder Optional InstallOperationManager for recording steps
      * @param options Optional server install options
      * @returns The status of the installation
      */
-    async install(requirement, options) {
-        try {
+    async install(requirement, recorder, options) {
+        return await recorder.recording(async () => {
             const status = await this.checkInstallation(requirement, options);
             if (status.installed && status.version && compareVersions(status.version, requirement.version) === 0 && !requirement.version.toLowerCase().includes('latest')) {
                 Logger.log(`${requirement.name}==${status.version} already installed for ${this.getPythonCommand}.`);
                 return status;
             }
             const pipCmd = this.getPipCommand(options);
+            let command;
             if (!requirement.registry) {
-                const { stderr } = await this.execPromise(`${pipCmd} install ${requirement.name}==${requirement.version}`);
-                if (stderr && stderr.toLowerCase().includes('error')) {
-                    throw new Error(stderr);
+                if (requirement.version && !requirement.version.includes('latest')) {
+                    command = `${pipCmd} install ${requirement.name}==${requirement.version}`;
+                }
+                else {
+                    command = `${pipCmd} install --upgrade ${requirement.name}`;
                 }
             }
             else {
@@ -127,45 +131,63 @@ export class PipInstaller extends BaseInstaller {
                 if (requirement.registry.githubRelease) {
                     const result = await handleGitHubRelease(requirement, requirement.registry.githubRelease);
                     packageSource = result.resolvedPath;
-                    const { stderr } = await this.execPromise(`${pipCmd} install "${packageSource}"`);
-                    if (stderr && stderr.toLowerCase().includes('error')) {
-                        throw new Error(stderr);
-                    }
+                    command = `${pipCmd} install "${packageSource}"`;
                 }
                 else if (requirement.registry.artifacts) {
                     const pythonCmd = this.getPythonCommand(options);
                     const adoArtifactResult = await handleAdoArtifact(requirement, requirement.registry.artifacts, pythonCmd);
-                    const { stderr } = await this.execPromise(`${pipCmd} install ${adoArtifactResult.package} --extra-index-url ${adoArtifactResult.registryUrl}`);
-                    if (stderr && stderr.toLowerCase().includes('error')) {
-                        const checkStatus = await this.checkInstallation(requirement, options);
-                        if (!checkStatus.installed) {
-                            throw new Error(`Pip installation failed with: ${stderr}`);
-                        }
-                    }
+                    command = `${pipCmd} install ${adoArtifactResult.package} --extra-index-url ${adoArtifactResult.registryUrl}`;
                 }
                 else {
+                    await recorder.recordStep('PipInstaller:RegistryConfig', 'failed', 'Invalid registry configuration');
                     throw new Error('Invalid registry configuration');
                 }
             }
-            return {
-                name: requirement.name,
-                type: 'pip',
-                installed: true,
-                version: requirement.version, // This might need to be updated to actual installed version
-                inProgress: false,
-                pythonEnv: this.getPythonCommand(options)
-            };
-        }
-        catch (error) {
-            return {
-                name: requirement.name,
-                type: 'pip',
-                installed: false,
-                error: error instanceof Error ? error.message : String(error),
-                inProgress: false,
-                pythonEnv: this.getPythonCommand(options)
-            };
-        }
+            return await recorder.recording(async () => {
+                const { stderr } = await this.execPromise(command);
+                if (stderr && stderr.toLowerCase().includes('error')) {
+                    Logger.debug(`Pip installation error: ${stderr}`);
+                    // wait for 5 seconds as python pip would be little delayed
+                    await new Promise(resolve => setTimeout(resolve, 5000));
+                    const checkStatus = await this.checkInstallation(requirement, options);
+                    if (!checkStatus.installed) {
+                        Logger.error(`Package not found after the command, ${stderr}`);
+                        throw new Error(`Pip installation failed with: ${stderr}`);
+                    }
+                }
+                return {
+                    name: requirement.name,
+                    type: 'pip',
+                    installed: true,
+                    version: requirement.version, // This might need to be updated to actual installed version
+                    inProgress: false,
+                    pythonEnv: this.getPythonCommand(options)
+                };
+            }, {
+                stepName: `${RecordingConstants.STEP_INSTALL_COMMAND_PREFIX}: ${requirement.name} : ${requirement.version}`,
+                inProgressMessage: `Running: ${command}`,
+                endMessage: (result) => result.installed ? `Succeeded: ${command}` : `Failed: ${command}`,
+            });
+        }, {
+            stepName: RecordingConstants.STEP_PIP_INSTALLER_INSTALL,
+            inProgressMessage: `Installing pip package: ${requirement.name}`,
+            endMessage: (result) => result.installed
+                ? `Install completed for ${requirement.name} with version ${result.version}`
+                : `Install failed for ${requirement.name}`,
+            onError: (error) => {
+                return {
+                    result: {
+                        name: requirement.name,
+                        type: 'pip',
+                        installed: false,
+                        error: error instanceof Error ? error.message : String(error),
+                        inProgress: false,
+                        pythonEnv: this.getPythonCommand(options)
+                    },
+                    message: error instanceof Error ? error.message : String(error),
+                };
+            },
+        });
     }
 }
 //# sourceMappingURL=PipInstaller.js.map

package/dist/core/installers/requirements/RequirementInstaller.d.ts

@@ -1,4 +1,5 @@
 import { RequirementConfig, RequirementStatus, ServerInstallOptions } from '../../metadatas/types.js';
+import { InstallOperationManager } from '../../loaders/InstallOperationManager.js';
 /**
  * Interface for requirement installers.
  * Implementations should handle specific requirement types.
@@ -14,9 +15,11 @@ export interface RequirementInstaller {
     /**
      * Install the requirement
      * @param requirement The requirement to install
+     * @param options Optional install options
+     * @param recorder Optional InstallOperationManager for recording steps
      * @returns The status of the installation
      */
-    install(requirement: RequirementConfig, options?: ServerInstallOptions): Promise<RequirementStatus>;
+    install(requirement: RequirementConfig, recorder: InstallOperationManager, options?: ServerInstallOptions): Promise<RequirementStatus>;
     /**
      * Check if the requirement is already installed
      * @param requirement The requirement to check

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;
+}