@juspay/neurolink 7.0.0 → 7.2.0

package/dist/lib/utils/logger.js

@@ -23,11 +23,7 @@ class NeuroLinkLogger {
             process.argv.includes("--debug") ||
                 process.env.NEUROLINK_DEBUG === "true";
         // Check NEUROLINK_LOG_LEVEL for consistency with the unified NeuroLink logger
-        let envLevel = process.env.NEUROLINK_LOG_LEVEL?.toLowerCase();
-        // Fallback to MCP_LOG_LEVEL for backward compatibility (if needed)
-        if (!envLevel) {
-            envLevel = process.env.MCP_LOG_LEVEL?.toLowerCase();
-        }
+        const envLevel = process.env.NEUROLINK_LOG_LEVEL?.toLowerCase();
         if (envLevel && ["debug", "info", "warn", "error"].includes(envLevel)) {
             this.logLevel = envLevel;
         }
@@ -36,8 +32,11 @@ class NeuroLinkLogger {
         this.logLevel = level;
     }
     shouldLog(level) {
+        // Dynamic debug mode check to handle CLI middleware timing
+        const currentDebugMode = process.argv.includes("--debug") ||
+            process.env.NEUROLINK_DEBUG === "true";
         // Hide all logs except errors unless debugging
-        if (!this.isDebugMode && level !== "error") {
+        if (!currentDebugMode && level !== "error") {
             return false;
         }
         const levels = ["debug", "info", "warn", "error"];
@@ -122,6 +121,14 @@ class NeuroLinkLogger {
     always(...args) {
         console.log(...args);
     }
+    /**
+     * Displays tabular data unconditionally using `console.table`.
+     *
+     * @param data - The data to display in table format
+     */
+    table(data) {
+        console.table(data);
+    }
 }
 // Export singleton instance
 const neuroLinkLogger = new NeuroLinkLogger();
@@ -167,6 +174,9 @@ export const logger = {
     always: (...args) => {
         neuroLinkLogger.always(...args);
     },
+    table: (data) => {
+        neuroLinkLogger.table(data);
+    },
     // Expose structured logging methods
     setLogLevel: (level) => neuroLinkLogger.setLogLevel(level),
     getLogs: (level) => neuroLinkLogger.getLogs(level),

package/dist/lib/utils/performance.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Performance measurement and memory management utilities
+ * Part of Sub-phase 3.3.1-3.3.2 optimization efforts
+ */
+export interface PerformanceMetrics {
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    memoryStart: NodeJS.MemoryUsage;
+    memoryEnd?: NodeJS.MemoryUsage;
+    memoryDelta?: {
+        rss: number;
+        heapTotal: number;
+        heapUsed: number;
+        external: number;
+    };
+}
+/**
+ * Performance measurement utility for tracking operations
+ */
+export declare class PerformanceTracker {
+    private metrics;
+    /**
+     * Start tracking performance for an operation
+     */
+    start(operationName: string): void;
+    /**
+     * End tracking and calculate metrics
+     */
+    end(operationName: string): PerformanceMetrics | null;
+    /**
+     * Get metrics for an operation
+     */
+    getMetrics(operationName: string): PerformanceMetrics | null;
+    /**
+     * Clear all metrics
+     */
+    clear(): void;
+    /**
+     * Format metrics for display
+     */
+    formatMetrics(operationName: string): string;
+}
+/**
+ * Global performance tracker instance
+ */
+export declare const globalTracker: PerformanceTracker;
+/**
+ * Memory management utilities
+ */
+export declare class MemoryManager {
+    /**
+     * Force garbage collection if available
+     */
+    static forceGC(): boolean;
+    /**
+     * Get current memory usage in MB
+     */
+    static getMemoryUsageMB(): {
+        rss: number;
+        heapTotal: number;
+        heapUsed: number;
+        external: number;
+    };
+    /**
+     * Monitor memory usage and warn if it exceeds threshold
+     */
+    static monitorMemory(threshold?: number): boolean;
+    /**
+     * Clean up and optimize memory usage.
+     * Attempts to force garbage collection if available.
+     *
+     * @returns {object|null} Memory usage statistics if cleanup was performed, or null if not possible.
+     *   - If manual garbage collection is not available (i.e., Node.js not run with --expose-gc),
+     *     no cleanup is performed and null is returned.
+     *   - Clearing the require cache is not attempted due to potential side effects.
+     */
+    static cleanup(): {
+        beforeMB: number;
+        afterMB: number;
+        freedMB: number;
+    } | null;
+}
+/**
+ * Decorator for tracking performance of async functions
+ */
+export declare function trackPerformance(operationName: string): <T extends (...args: unknown[]) => Promise<unknown>>(target: unknown, propertyName: string, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T>;
+/**
+ * Performance monitoring for CLI operations
+ */
+export declare class CLIPerformanceMonitor {
+    private static instance;
+    private enabled;
+    static getInstance(): CLIPerformanceMonitor;
+    enable(): void;
+    disable(): void;
+    /**
+     * Monitor a CLI operation
+     */
+    monitorOperation<T>(operationName: string, operation: () => Promise<T>): Promise<T>;
+}
+/**
+ * Export singleton monitor for easy access
+ */
+export declare const cliMonitor: CLIPerformanceMonitor;

package/dist/lib/utils/performance.js

@@ -0,0 +1,210 @@
+/**
+ * Performance measurement and memory management utilities
+ * Part of Sub-phase 3.3.1-3.3.2 optimization efforts
+ */
+import { logger } from "./logger.js";
+/**
+ * Performance measurement utility for tracking operations
+ */
+export class PerformanceTracker {
+    metrics = new Map();
+    /**
+     * Start tracking performance for an operation
+     */
+    start(operationName) {
+        this.metrics.set(operationName, {
+            startTime: Date.now(),
+            memoryStart: process.memoryUsage(),
+        });
+    }
+    /**
+     * End tracking and calculate metrics
+     */
+    end(operationName) {
+        const metric = this.metrics.get(operationName);
+        if (!metric) {
+            return null;
+        }
+        const endTime = Date.now();
+        const memoryEnd = process.memoryUsage();
+        const completedMetric = {
+            ...metric,
+            endTime,
+            duration: endTime - metric.startTime,
+            memoryEnd,
+            memoryDelta: {
+                rss: memoryEnd.rss - metric.memoryStart.rss,
+                heapTotal: memoryEnd.heapTotal - metric.memoryStart.heapTotal,
+                heapUsed: memoryEnd.heapUsed - metric.memoryStart.heapUsed,
+                external: memoryEnd.external - metric.memoryStart.external,
+            },
+        };
+        this.metrics.set(operationName, completedMetric);
+        return completedMetric;
+    }
+    /**
+     * Get metrics for an operation
+     */
+    getMetrics(operationName) {
+        return this.metrics.get(operationName) || null;
+    }
+    /**
+     * Clear all metrics
+     */
+    clear() {
+        this.metrics.clear();
+    }
+    /**
+     * Format metrics for display
+     */
+    formatMetrics(operationName) {
+        const metric = this.metrics.get(operationName);
+        if (!metric || !metric.duration) {
+            return `${operationName}: No metrics available`;
+        }
+        const memoryMB = (bytes) => (bytes / 1024 / 1024).toFixed(1);
+        return [
+            `${operationName}:`,
+            `  Duration: ${metric.duration}ms`,
+            `  Memory Delta: +${memoryMB(metric.memoryDelta.heapUsed)}MB heap`,
+            `  RSS Delta: +${memoryMB(metric.memoryDelta.rss)}MB`,
+        ].join("\n");
+    }
+}
+/**
+ * Global performance tracker instance
+ */
+export const globalTracker = new PerformanceTracker();
+/**
+ * Memory management utilities
+ */
+export class MemoryManager {
+    /**
+     * Force garbage collection if available
+     */
+    static forceGC() {
+        if (typeof global !== "undefined" && global.gc) {
+            global.gc();
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get current memory usage in MB
+     */
+    static getMemoryUsageMB() {
+        const usage = process.memoryUsage();
+        return {
+            rss: Math.round(usage.rss / 1024 / 1024),
+            heapTotal: Math.round(usage.heapTotal / 1024 / 1024),
+            heapUsed: Math.round(usage.heapUsed / 1024 / 1024),
+            external: Math.round(usage.external / 1024 / 1024),
+        };
+    }
+    /**
+     * Monitor memory usage and warn if it exceeds threshold
+     */
+    static monitorMemory(threshold = 100) {
+        const usage = this.getMemoryUsageMB();
+        if (usage.heapUsed > threshold) {
+            logger.warn(`⚠️ High memory usage: ${usage.heapUsed}MB heap (threshold: ${threshold}MB)`);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Clean up and optimize memory usage.
+     * Attempts to force garbage collection if available.
+     *
+     * @returns {object|null} Memory usage statistics if cleanup was performed, or null if not possible.
+     *   - If manual garbage collection is not available (i.e., Node.js not run with --expose-gc),
+     *     no cleanup is performed and null is returned.
+     *   - Clearing the require cache is not attempted due to potential side effects.
+     */
+    static cleanup() {
+        const before = this.getMemoryUsageMB();
+        const gcForced = this.forceGC();
+        if (!gcForced) {
+            // Manual garbage collection not available.
+            // No cleanup performed. Clearing require cache is dangerous and not attempted.
+            // Memory cleanup relies on Node.js natural garbage collection.
+            return null;
+        }
+        const after = this.getMemoryUsageMB();
+        return {
+            beforeMB: before.heapUsed,
+            afterMB: after.heapUsed,
+            freedMB: before.heapUsed - after.heapUsed,
+        };
+    }
+}
+/**
+ * Decorator for tracking performance of async functions
+ */
+export function trackPerformance(operationName) {
+    return function (target, propertyName, descriptor) {
+        const method = descriptor.value;
+        descriptor.value = async function (...args) {
+            globalTracker.start(operationName);
+            try {
+                const result = await method.apply(this, args);
+                globalTracker.end(operationName);
+                return result;
+            }
+            catch (error) {
+                globalTracker.end(operationName);
+                throw error;
+            }
+        };
+        return descriptor;
+    };
+}
+/**
+ * Performance monitoring for CLI operations
+ */
+export class CLIPerformanceMonitor {
+    static instance;
+    enabled = false;
+    static getInstance() {
+        if (!CLIPerformanceMonitor.instance) {
+            CLIPerformanceMonitor.instance = new CLIPerformanceMonitor();
+        }
+        return CLIPerformanceMonitor.instance;
+    }
+    enable() {
+        this.enabled = true;
+    }
+    disable() {
+        this.enabled = false;
+    }
+    /**
+     * Monitor a CLI operation
+     */
+    async monitorOperation(operationName, operation) {
+        if (!this.enabled) {
+            return operation();
+        }
+        globalTracker.start(operationName);
+        const startMemory = MemoryManager.getMemoryUsageMB();
+        try {
+            const result = await operation();
+            const metrics = globalTracker.end(operationName);
+            const endMemory = MemoryManager.getMemoryUsageMB();
+            if (metrics) {
+                logger.debug(`\n🔍 Performance: ${operationName}`);
+                logger.debug(`   Duration: ${metrics.duration}ms`);
+                logger.debug(`   Memory: ${startMemory.heapUsed}MB → ${endMemory.heapUsed}MB`);
+                logger.debug(`   Delta: +${endMemory.heapUsed - startMemory.heapUsed}MB`);
+            }
+            return result;
+        }
+        catch (error) {
+            globalTracker.end(operationName);
+            throw error;
+        }
+    }
+}
+/**
+ * Export singleton monitor for easy access
+ */
+export const cliMonitor = CLIPerformanceMonitor.getInstance();

package/dist/lib/utils/providerUtils.js

@@ -105,10 +105,17 @@ export function hasProviderEnvVars(provider) {
         case "aws":
             return !!(process.env.AWS_ACCESS_KEY_ID && process.env.AWS_SECRET_ACCESS_KEY);
         case "vertex":
+        case "googlevertex":
         case "google":
         case "gemini":
-            return !!(process.env.GOOGLE_VERTEX_PROJECT ||
-                process.env.GOOGLE_APPLICATION_CREDENTIALS);
+            return !!((process.env.GOOGLE_CLOUD_PROJECT_ID ||
+                process.env.VERTEX_PROJECT_ID ||
+                process.env.GOOGLE_VERTEX_PROJECT ||
+                process.env.GOOGLE_CLOUD_PROJECT) &&
+                (process.env.GOOGLE_APPLICATION_CREDENTIALS ||
+                    process.env.GOOGLE_SERVICE_ACCOUNT_KEY ||
+                    (process.env.GOOGLE_AUTH_CLIENT_EMAIL &&
+                        process.env.GOOGLE_AUTH_PRIVATE_KEY)));
         case "openai":
         case "gpt":
             return !!process.env.OPENAI_API_KEY;

package/dist/lib/utils/retryHandler.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Retry and resilience utilities for NeuroLink
+ * Part of Sub-phase 3.3.3 - Edge Case Handling
+ */
+/**
+ * Calculate exponential backoff delay with jitter
+ * @param attempt - Current attempt number (1-based)
+ * @param initialDelay - Initial delay in milliseconds
+ * @param multiplier - Backoff multiplier for exponential growth
+ * @param maxDelay - Maximum delay cap in milliseconds
+ * @param addJitter - Whether to add random jitter to prevent thundering herd
+ * @returns Calculated delay in milliseconds
+ */
+export declare function calculateBackoffDelay(attempt: number, initialDelay?: number, multiplier?: number, maxDelay?: number, addJitter?: boolean): number;
+export interface RetryOptions {
+    maxAttempts?: number;
+    initialDelay?: number;
+    maxDelay?: number;
+    backoffMultiplier?: number;
+    retryCondition?: (error: unknown) => boolean;
+    onRetry?: (attempt: number, error: unknown) => void;
+}
+/**
+ * Error types that are typically retryable
+ */
+export declare class NetworkError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+export declare class TemporaryError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Default retry configuration
+ */
+export declare const DEFAULT_RETRY_CONFIG: Required<RetryOptions>;
+/**
+ * Execute an operation with retry logic
+ */
+export declare function withRetry<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Enhanced timeout with retry for network operations
+ */
+export declare function withTimeoutAndRetry<T>(operation: () => Promise<T>, timeoutMs: number, retryOptions?: RetryOptions): Promise<T>;
+/**
+ * Circuit breaker pattern for preventing cascading failures
+ */
+export declare class CircuitBreaker {
+    private threshold;
+    private timeout;
+    private monitorWindow;
+    private failures;
+    private lastFailureTime;
+    private state;
+    constructor(threshold?: number, timeout?: number, // 1 minute
+    monitorWindow?: number);
+    execute<T>(operation: () => Promise<T>): Promise<T>;
+    private onSuccess;
+    private onFailure;
+    getState(): string;
+    reset(): void;
+}
+/**
+ * Rate limiter to prevent overwhelming APIs
+ */
+export declare class RateLimiter {
+    private maxRequests;
+    private windowMs;
+    private requests;
+    constructor(maxRequests: number, windowMs: number);
+    acquire(): Promise<void>;
+}
+/**
+ * Utility for graceful shutdown handling
+ */
+export declare class GracefulShutdown {
+    private operations;
+    private shutdownPromise;
+    track<T>(operation: Promise<T>): Promise<T>;
+    shutdown(timeoutMs?: number): Promise<void>;
+    private performShutdown;
+}
+/**
+ * Global instances for convenience
+ */
+export declare const globalShutdown: GracefulShutdown;
+export declare const providerCircuitBreaker: CircuitBreaker;
+export declare const apiRateLimiter: RateLimiter;