@juspay/neurolink 9.30.0 → 9.31.1

package/dist/client/utils/logger.js

@@ -0,0 +1,491 @@
+/**
+ * NeuroLink Unified Logger Utility
+ *
+ * Centralized logging for the entire NeuroLink ecosystem.
+ * Provides structured logging with different severity levels and consistent formatting.
+ * Supports both CLI --debug flag and NEUROLINK_DEBUG environment variable.
+ * Maintains compatibility with MCP logging while providing enhanced features.
+ *
+ * Features:
+ * - Multiple log levels (debug, info, warn, error)
+ * - Log history retention with configurable limits
+ * - Conditional logging based on environment settings
+ * - Structured data support for complex objects
+ * - Tabular data display
+ */
+// OTel trace context for log correlation (optional — gracefully no-ops if OTel not initialized)
+let traceApi = null;
+let traceApiPromise = null;
+async function getTraceApi() {
+    if (!traceApiPromise) {
+        traceApiPromise = import("@opentelemetry/api")
+            .then((mod) => {
+            traceApi = mod;
+            return mod;
+        })
+            .catch(() => null);
+    }
+    return traceApiPromise;
+}
+// Eagerly kick off the import so the cached value is available for synchronous callers
+void getTraceApi();
+// Pre-computed uppercase log levels for performance optimization
+const UPPERCASE_LOG_LEVELS = {
+    debug: "DEBUG",
+    info: "INFO",
+    warn: "WARN",
+    error: "ERROR",
+};
+class NeuroLinkLogger {
+    logLevel = "info";
+    logs = [];
+    maxLogs = 1000;
+    isDebugMode;
+    eventEmitter;
+    constructor() {
+        // Cache debug mode check to avoid repeated array searches
+        this.isDebugMode =
+            process.argv.includes("--debug") ||
+                process.env.NEUROLINK_DEBUG === "true";
+        // Check NEUROLINK_LOG_LEVEL for consistency with the unified NeuroLink logger
+        const envLevel = process.env.NEUROLINK_LOG_LEVEL?.toLowerCase();
+        if (envLevel && ["debug", "info", "warn", "error"].includes(envLevel)) {
+            this.logLevel = envLevel;
+        }
+    }
+    /**
+     * Sets the event emitter that will receive log events.
+     * When set, all log operations will emit a "log-event" event.
+     *
+     * @param emitter - The event emitter instance
+     */
+    setEventEmitter(emitter) {
+        this.eventEmitter = emitter;
+    }
+    /**
+     * Clears the event emitter reference.
+     * Should be called when a NeuroLink instance is disposed to prevent memory leaks.
+     */
+    clearEventEmitter() {
+        this.eventEmitter = undefined;
+    }
+    /**
+     * Sets the minimum log level that will be processed and output.
+     * Log messages with a level lower than this will be ignored.
+     *
+     * @param level - The minimum log level to process ("debug", "info", "warn", or "error")
+     */
+    setLogLevel(level) {
+        this.logLevel = level;
+    }
+    /**
+     * Determines whether a message with the given log level should be processed.
+     * This method considers both the configured log level and the current debug mode.
+     *
+     * Logic:
+     * 1. If not in debug mode, only error messages are allowed
+     * 2. If in debug mode, messages at or above the configured log level are allowed
+     *
+     * @param level - The log level to check
+     * @returns True if a message with this level should be logged, false otherwise
+     */
+    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 (!currentDebugMode && level !== "error") {
+            return false;
+        }
+        const levels = ["debug", "info", "warn", "error"];
+        return levels.indexOf(level) >= levels.indexOf(this.logLevel);
+    }
+    /**
+     * Generates a standardized prefix for log messages.
+     * The prefix includes a timestamp and the log level in a consistent format.
+     *
+     * @param timestamp - ISO string representation of the log timestamp
+     * @param level - The log level for this message
+     * @returns Formatted prefix string like "[2025-08-18T13:45:30.123Z] [NEUROLINK:ERROR]"
+     */
+    getLogPrefix(timestamp, level) {
+        return `[${timestamp}] [NEUROLINK:${UPPERCASE_LOG_LEVELS[level]}]`;
+    }
+    /**
+     * Extracts current OTel trace context (trace_id, span_id) if available.
+     * Returns empty object if OTel is not initialized or no active span exists.
+     */
+    getTraceContext() {
+        if (!traceApi) {
+            return {};
+        }
+        try {
+            const span = traceApi.trace.getSpan(traceApi.context.active());
+            if (!span) {
+                return {};
+            }
+            const spanContext = span.spanContext();
+            if (!spanContext ||
+                spanContext.traceId === "00000000000000000000000000000000") {
+                return {};
+            }
+            return {
+                trace_id: spanContext.traceId,
+                span_id: spanContext.spanId,
+                trace_flags: String(spanContext.traceFlags),
+            };
+        }
+        catch {
+            return {};
+        }
+    }
+    /**
+     * Safely serialize data to fully expanded JSON string.
+     * Handles circular references and non-serializable values.
+     * Zero truncation — all nested objects and arrays are fully expanded.
+     */
+    serializeData(data) {
+        if (data === undefined || data === null) {
+            return String(data);
+        }
+        if (typeof data !== "object") {
+            return String(data);
+        }
+        try {
+            return JSON.stringify(data, (_key, value) => {
+                if (value instanceof Error) {
+                    return {
+                        name: value.name,
+                        message: value.message,
+                        stack: value.stack,
+                    };
+                }
+                return value;
+            });
+        }
+        catch {
+            // Handle circular references using a stack-based approach
+            // to avoid false "[Circular]" on diamond (shared) references
+            const ancestors = [];
+            try {
+                return JSON.stringify(data, function (_key, value) {
+                    if (value instanceof Error) {
+                        return {
+                            name: value.name,
+                            message: value.message,
+                            stack: value.stack,
+                        };
+                    }
+                    if (typeof value === "object" && value !== null) {
+                        // Only flag actual circular (ancestor) references
+                        if (ancestors.includes(value)) {
+                            return "[Circular]";
+                        }
+                        ancestors.push(value);
+                    }
+                    return value;
+                });
+            }
+            catch {
+                return "[Unserializable Object]";
+            }
+        }
+    }
+    /**
+     * Outputs a log entry to the console based on the log level.
+     * Data is fully serialized to JSON — no [Object] or [Array] truncation.
+     *
+     * @param level - The log level (debug, info, warn, error).
+     * @param prefix - The formatted log prefix.
+     * @param message - The log message.
+     * @param data - Optional additional data to log.
+     */
+    outputToConsole(level, prefix, message, data) {
+        const logMethod = {
+            debug: console.debug,
+            info: console.info,
+            warn: console.warn,
+            error: console.error,
+        }[level];
+        const traceCtx = this.getTraceContext();
+        const tracePrefix = traceCtx.trace_id
+            ? ` [trace_id=${traceCtx.trace_id} span_id=${traceCtx.span_id}]`
+            : "";
+        if (data !== undefined && data !== null) {
+            logMethod(prefix + tracePrefix, message, this.serializeData(data));
+        }
+        else {
+            logMethod(prefix + tracePrefix, message);
+        }
+    }
+    /**
+     * Core internal logging method that handles:
+     * 1. Creating log entries with consistent format
+     * 2. Storing entries in the log history
+     * 3. Managing log rotation to prevent memory issues
+     * 4. Outputting formatted logs to the console
+     * 5. Emitting log events if an event emitter is configured
+     *
+     * This is the central method called by all specific logging methods (debug, info, etc.)
+     *
+     * @param level - The severity level for this log entry
+     * @param message - The message text to log
+     * @param data - Optional additional context data to include
+     */
+    log(level, message, data) {
+        if (!this.shouldLog(level)) {
+            return;
+        }
+        const entry = {
+            level,
+            message,
+            timestamp: new Date(),
+            data,
+        };
+        // Emit log event if emitter is configured
+        if (this.eventEmitter) {
+            try {
+                this.eventEmitter.emit("log-event", {
+                    level,
+                    message,
+                    timestamp: new Date().getTime(),
+                    data,
+                });
+            }
+            catch {
+                // Silently ignore emitter errors to avoid disrupting logging
+            }
+        }
+        // Store log entry
+        this.logs.push(entry);
+        // Trim old logs
+        if (this.logs.length > this.maxLogs) {
+            this.logs = this.logs.slice(-this.maxLogs);
+        }
+        // Console output
+        const timestamp = entry.timestamp.toISOString();
+        const prefix = this.getLogPrefix(timestamp, level);
+        this.outputToConsole(level, prefix, message, data);
+    }
+    /**
+     * Logs a message at the debug level.
+     * Used for detailed troubleshooting information.
+     *
+     * @param message - The message to log
+     * @param data - Optional additional context data
+     */
+    debug(message, data) {
+        this.log("debug", message, data);
+    }
+    /**
+     * Logs a message at the info level.
+     * Used for general information about system operation.
+     *
+     * @param message - The message to log
+     * @param data - Optional additional context data
+     */
+    info(message, data) {
+        this.log("info", message, data);
+    }
+    /**
+     * Logs a message at the warn level.
+     * Used for potentially problematic situations that don't prevent operation.
+     *
+     * @param message - The message to log
+     * @param data - Optional additional context data
+     */
+    warn(message, data) {
+        this.log("warn", message, data);
+    }
+    /**
+     * Logs a message at the error level.
+     * Used for critical issues that may cause failures.
+     *
+     * @param message - The message to log
+     * @param data - Optional additional context data
+     */
+    error(message, data) {
+        this.log("error", message, data);
+    }
+    /**
+     * Retrieves stored log entries, optionally filtered by log level.
+     * Returns a copy of the log entries to prevent external modification.
+     *
+     * @param level - Optional log level to filter by
+     * @returns Array of log entries, either all or filtered by level
+     */
+    getLogs(level) {
+        if (level) {
+            return this.logs.filter((log) => log.level === level);
+        }
+        return [...this.logs];
+    }
+    /**
+     * Removes all stored log entries.
+     * Useful for testing or when log history is no longer needed.
+     */
+    clearLogs() {
+        this.logs = [];
+    }
+    /**
+     * Logs messages unconditionally using `console.log`.
+     *
+     * This method is part of a legacy simple logger interface for backward compatibility.
+     * It bypasses the structured logging mechanism and should only be used when
+     * unstructured, unconditional logging is required.
+     *
+     * Use with caution in production environments as it outputs to the console
+     * regardless of the current log level or debug mode settings.
+     *
+     * Use cases:
+     * - Critical system information that must always be visible
+     * - Status messages during initialization before logging is fully configured
+     * - Debugging in environments where normal logging might be suppressed
+     *
+     * @param args - The arguments to log. These are passed directly to `console.log`.
+     */
+    always(...args) {
+        console.log(...args);
+    }
+    /**
+     * Displays tabular data unconditionally using `console.table`.
+     *
+     * Similar to the `always` method, this bypasses log level checks and
+     * will display data regardless of current logging settings.
+     *
+     * Important differences from other logging methods:
+     * - Does NOT store entries in the log history
+     * - Does NOT use the structured logging format with timestamps and prefixes
+     * - Outputs directly to console without additional formatting
+     *
+     * Particularly useful for:
+     * - Displaying structured data in a readable format during debugging
+     * - Showing configuration options and their current values
+     * - Presenting comparison data between different system states
+     * - Performance metrics and timing data
+     *
+     * @param data - The data to display in table format. Can be an array of objects or an object with key-value pairs.
+     */
+    table(data) {
+        console.table(data);
+    }
+}
+// Export singleton instance to ensure consistent logging across the application
+const neuroLinkLogger = new NeuroLinkLogger();
+/**
+ * Helper function to process logger arguments with minimal overhead.
+ * Handles variable argument patterns and ensures safe serialization of objects.
+ *
+ * This function:
+ * 1. Extracts the first argument as the message
+ * 2. Handles serialization of non-string first arguments
+ * 3. Collects remaining arguments as additional data
+ * 4. Passes the processed arguments to the actual logging method
+ *
+ * @param args - Array of arguments passed to the logger
+ * @param logMethod - Function that will perform the actual logging
+ */
+function processLoggerArgs(args, logMethod) {
+    if (args.length === 0) {
+        return;
+    }
+    // Serialize the first argument robustly to handle complex objects
+    const message = (() => {
+        try {
+            return typeof args[0] === "string" ? args[0] : JSON.stringify(args[0]);
+        }
+        catch {
+            return "[Unserializable Object]";
+        }
+    })();
+    const data = args.length === 2 ? args[1] : args.length > 2 ? args.slice(1) : undefined;
+    logMethod(message, data);
+}
+/**
+ * Main unified logger export that provides a simplified API for logging.
+ * This is the primary interface that should be used by application code.
+ *
+ * Features:
+ * - Convenient logging methods (debug, info, warn, error)
+ * - Unconditional logging (always, table)
+ * - Log level control and configuration
+ * - Log history management
+ * - Event emission for all log operations (when emitter is configured)
+ */
+export const logger = {
+    debug: (...args) => {
+        if (neuroLinkLogger.shouldLog("debug")) {
+            processLoggerArgs(args, (message, data) => neuroLinkLogger.debug(message, data));
+        }
+    },
+    info: (...args) => {
+        if (neuroLinkLogger.shouldLog("info")) {
+            processLoggerArgs(args, (message, data) => neuroLinkLogger.info(message, data));
+        }
+    },
+    warn: (...args) => {
+        if (neuroLinkLogger.shouldLog("warn")) {
+            processLoggerArgs(args, (message, data) => neuroLinkLogger.warn(message, data));
+        }
+    },
+    error: (...args) => {
+        if (neuroLinkLogger.shouldLog("error")) {
+            processLoggerArgs(args, (message, data) => neuroLinkLogger.error(message, data));
+        }
+    },
+    always: (...args) => {
+        neuroLinkLogger.always(...args);
+    },
+    table: (data) => {
+        neuroLinkLogger.table(data);
+    },
+    // Expose log-level check for gating expensive operations
+    shouldLog: (level) => neuroLinkLogger.shouldLog(level),
+    // Expose structured logging methods
+    setLogLevel: (level) => neuroLinkLogger.setLogLevel(level),
+    getLogs: (level) => neuroLinkLogger.getLogs(level),
+    clearLogs: () => neuroLinkLogger.clearLogs(),
+    setEventEmitter: (emitter) => neuroLinkLogger.setEventEmitter(emitter),
+    clearEventEmitter: () => neuroLinkLogger.clearEventEmitter(),
+};
+/**
+ * MCP compatibility exports - all use the same unified logger instance.
+ * These exports maintain backward compatibility with code that expects
+ * separate loggers for different MCP components, while actually using
+ * the same underlying logger instance.
+ */
+export const mcpLogger = neuroLinkLogger;
+export const autoDiscoveryLogger = neuroLinkLogger;
+export const registryLogger = neuroLinkLogger;
+export const unifiedRegistryLogger = neuroLinkLogger;
+/**
+ * Sets the global log level for all MCP-related logging.
+ * This function provides a convenient way to adjust logging verbosity
+ * for all MCP components at once.
+ *
+ * @param level - The log level to set ("debug", "info", "warn", or "error")
+ */
+export function setGlobalMCPLogLevel(level) {
+    neuroLinkLogger.setLogLevel(level);
+}
+/**
+ * Export LogLevel enum for runtime use.
+ * Provides type-safe log level constants for use in application code.
+ *
+ * Example usage:
+ * ```
+ * import { logger, LogLevels } from './logger';  // Import from your project's path
+ *
+ * // Using the LogLevels constants (recommended for type safety):
+ * logger.setLogLevel(LogLevels.debug);
+ *
+ * // Or directly using string values:
+ * logger.setLogLevel('debug');
+ * ```
+ */
+export const LogLevels = {
+    debug: "debug",
+    info: "info",
+    warn: "warn",
+    error: "error",
+};

package/dist/client/utils/mcpDefaults.js

@@ -0,0 +1,134 @@
+/**
+ * Smart Defaults for MCPServerInfo Creation
+ * Eliminates boilerplate manual object creation
+ */
+/**
+ * Smart category detection based on context
+ */
+export function detectCategory(context) {
+    // If category is already provided, validate and use it
+    if (context.existingCategory) {
+        const validCategories = [
+            "external",
+            "in-memory",
+            "built-in",
+            "user-defined",
+        ];
+        if (validCategories.includes(context.existingCategory)) {
+            return context.existingCategory;
+        }
+    }
+    // Smart detection based on context
+    if (context.isCustomTool) {
+        return "user-defined";
+    }
+    if (context.isBuiltIn) {
+        return "built-in";
+    }
+    if (context.isExternal) {
+        return "external";
+    }
+    if (context.serverId?.startsWith("custom-tool-")) {
+        return "user-defined";
+    }
+    if (context.serverId?.includes("external")) {
+        return "external";
+    }
+    if (context.serverId === "direct") {
+        return "built-in";
+    }
+    // Default to in-memory for most cases
+    return "in-memory";
+}
+/**
+ * Generate smart description based on name and category
+ */
+function generateDescription(name, category) {
+    // Generate descriptions based on category for better context
+    switch (category) {
+        case "external":
+            return `External MCP server: ${name}`;
+        case "built-in":
+            return `Built-in tool server: ${name}`;
+        case "custom":
+        case "user-defined":
+            return `Custom tool server: ${name}`;
+        case "in-memory":
+            return `In-memory MCP server: ${name}`;
+        default:
+            return name;
+    }
+}
+/**
+ * Create MCPServerInfo with smart defaults
+ * Eliminates manual boilerplate object creation
+ */
+export function createMCPServerInfo(options) {
+    const id = options.id || `server-${options.name}`;
+    const category = options.category ||
+        detectCategory({
+            isCustomTool: options.isCustomTool,
+            isExternal: options.isExternal,
+            isBuiltIn: options.isBuiltIn,
+            serverId: id,
+        });
+    const tools = options.tools || (options.tool ? [options.tool] : []);
+    return {
+        id,
+        name: options.name,
+        transport: options.transport || "stdio",
+        status: options.status || "connected",
+        tools,
+        description: options.description || generateDescription(options.name, category),
+        ...(options.command && { command: options.command }),
+        ...(options.args && { args: options.args }),
+        ...(options.env && { env: options.env }),
+        metadata: {
+            category: category,
+            toolCount: tools.length,
+        },
+    };
+}
+/**
+ * Create MCPServerInfo for custom tool registration
+ * Specialized version with smart defaults for registerTool usage
+ */
+export function createCustomToolServerInfo(toolName, tool, timeoutMs, maxRetries) {
+    const serverInfo = createMCPServerInfo({
+        id: `custom-tool-${toolName}`,
+        name: toolName,
+        tool: {
+            name: toolName,
+            description: tool.description || toolName,
+            inputSchema: tool.inputSchema || {},
+            execute: tool.execute,
+        },
+        isCustomTool: true,
+    });
+    if (serverInfo.metadata) {
+        if (timeoutMs !== undefined) {
+            serverInfo.metadata.toolTimeoutMs = timeoutMs;
+        }
+        if (maxRetries !== undefined) {
+            serverInfo.metadata.toolMaxRetries = maxRetries;
+        }
+    }
+    return serverInfo;
+}
+/**
+ * Create MCPServerInfo for external servers
+ * Specialized version with smart defaults for external server usage
+ */
+export function createExternalServerInfo(options) {
+    return createMCPServerInfo({
+        id: options.id,
+        name: options.name || options.id,
+        tools: options.tools || [],
+        transport: options.transport || "stdio",
+        description: options.description || options.name || options.id,
+        isExternal: true,
+        command: options.command,
+        args: options.args,
+        env: options.env,
+    });
+}