@loop_ouroboros/mcp-hub-lite 1.0.0

package/dist/server/src/utils/json-utils.js

@@ -0,0 +1,204 @@
+/**
+ * JSON utilities for logging and formatting
+ */
+/**
+ * Flag to track if dev mode is enabled.
+ * Set by logger.enableDevLog() to avoid circular dependencies.
+ */
+let _isDevModeEnabled = false;
+/**
+ * Set the dev mode flag.
+ * Called by logger.enableDevLog() to indicate we're in dev mode.
+ *
+ * @param enabled - Whether dev mode is enabled
+ */
+export function setDevModeEnabled(enabled) {
+    _isDevModeEnabled = enabled;
+}
+/**
+ * Get the dev mode flag.
+ * Returns true if we're in dev mode (dev log is enabled).
+ *
+ * @returns boolean indicating whether dev mode is enabled
+ */
+export function isDevModeEnabled() {
+    return _isDevModeEnabled;
+}
+/**
+ * Get default value for config settings based on dev mode.
+ * In dev mode, debugging settings default to true if not explicitly configured.
+ *
+ * @param defaultValue - The default value for production mode
+ * @returns The appropriate default value based on current mode
+ */
+function getDefaultForDevMode(defaultValue) {
+    if (_isDevModeEnabled) {
+        return true;
+    }
+    return defaultValue;
+}
+/**
+ * Post-process pretty-printed JSON to convert \n to actual newlines in string values.
+ * This makes multi-line text more readable in logs.
+ *
+ * @param jsonStr - The JSON string to process
+ * @returns Processed JSON string with actual newlines in string values
+ */
+function processPrettyJsonForLogging(jsonStr) {
+    // Only process if we have actual newlines in the string
+    if (!jsonStr.includes('\\n')) {
+        return jsonStr;
+    }
+    // Replace \n with actual newlines, but be careful not to break JSON structure
+    // We need to track whether we're inside a string
+    let result = '';
+    let inString = false;
+    let escapeNext = false;
+    for (let i = 0; i < jsonStr.length; i++) {
+        const char = jsonStr[i];
+        if (escapeNext) {
+            if (inString && char === 'n') {
+                // Replace \n with actual newline inside strings
+                result += '\n';
+            }
+            else {
+                // Keep other escaped characters as-is
+                result += '\\' + char;
+            }
+            escapeNext = false;
+        }
+        else if (char === '\\') {
+            escapeNext = true;
+        }
+        else if (char === '"') {
+            inString = !inString;
+            result += char;
+        }
+        else {
+            result += char;
+        }
+    }
+    // Handle any trailing escape
+    if (escapeNext) {
+        result += '\\';
+    }
+    return result;
+}
+/**
+ * Optional config getter to retrieve jsonPretty setting from config.
+ * This avoids circular dependency issues.
+ */
+let _configGetter = null;
+/**
+ * Set the config getter for jsonPretty setting.
+ * This allows retrieving the setting from config without direct import dependency.
+ *
+ * @param getter - Function that returns the config object, or null to reset
+ */
+export function setJsonPrettyConfigGetter(getter) {
+    _configGetter = getter;
+}
+/**
+ * Convert Node.js rawHeaders array [key1, value1, key2, value2, ...] to object
+ * @param rawHeaders Node.js rawHeaders array
+ * @returns Headers as key-value object
+ */
+export function rawHeadersToObject(rawHeaders) {
+    const result = {};
+    for (let i = 0; i < rawHeaders.length; i += 2) {
+        const key = rawHeaders[i];
+        const value = rawHeaders[i + 1];
+        if (key !== undefined && value !== undefined) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Stringify Node.js rawHeaders array for logging
+ * Converts [key1, value1, key2, value2, ...] to readable object format
+ * @param rawHeaders Node.js rawHeaders array
+ * @returns Formatted JSON string
+ */
+export function stringifyRawHeadersForLogging(rawHeaders) {
+    const headersObj = rawHeadersToObject(rawHeaders);
+    return stringifyForLogging(headersObj);
+}
+/**
+ * Get JSON pretty setting from config getter.
+ *
+ * @returns boolean indicating whether to use pretty JSON formatting
+ */
+export function getJsonPrettySetting() {
+    if (_configGetter) {
+        try {
+            const config = _configGetter();
+            return config.system.logging.jsonPretty;
+        }
+        catch {
+            // Fall through to default if config getter fails
+        }
+    }
+    return true; // Default to true (matches current default in config schema)
+}
+/**
+ * Get MCP communication debug setting from config getter.
+ *
+ * @returns boolean indicating whether to enable MCP communication debug logging
+ */
+export function getMcpCommDebugSetting() {
+    if (_configGetter) {
+        try {
+            const config = _configGetter();
+            return config.system.logging.mcpCommDebug;
+        }
+        catch {
+            // Fall through to default if config getter fails
+        }
+    }
+    return getDefaultForDevMode(false);
+}
+/**
+ * Get session debug setting from config getter.
+ *
+ * @returns boolean indicating whether to enable session debug logging
+ */
+export function getSessionDebugSetting() {
+    if (_configGetter) {
+        try {
+            const config = _configGetter();
+            return config.system.logging.sessionDebug;
+        }
+        catch {
+            // Fall through to default if config getter fails
+        }
+    }
+    return getDefaultForDevMode(false);
+}
+/**
+ * Stringify object for logging with dynamic pretty formatting based on LOG_JSON_PRETTY environment variable
+ * @param obj Object to stringify
+ * @returns Formatted JSON string
+ */
+export function stringifyForLogging(obj) {
+    const jsonPretty = getJsonPrettySetting();
+    if (jsonPretty) {
+        const jsonStr = JSON.stringify(obj, null, 2);
+        return processPrettyJsonForLogging(jsonStr);
+    }
+    return JSON.stringify(obj);
+}
+/**
+ * Stringify object for logging with replacer and dynamic pretty formatting based on LOG_JSON_PRETTY environment variable
+ * @param obj Object to stringify
+ * @param replacer Optional replacer function
+ * @returns Formatted JSON string
+ */
+export function stringifyForLoggingWithReplacer(obj, replacer) {
+    const jsonPretty = getJsonPrettySetting();
+    if (jsonPretty) {
+        const jsonStr = JSON.stringify(obj, replacer, 2);
+        return processPrettyJsonForLogging(jsonStr);
+    }
+    return JSON.stringify(obj, replacer);
+}

package/dist/server/src/utils/log-rotator.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Configuration interface for custom log rotation settings.
+ */
+export interface RotatorConfig {
+    rotationAge?: string;
+}
+/**
+ * Type for the config getter function to avoid direct import dependency.
+ */
+type ConfigGetter = () => {
+    system: {
+        logging: {
+            rotationAge: string;
+        };
+    };
+};
+/**
+ * Manages log file rotation and cleanup for MCP Hub Lite.
+ *
+ * This class provides automated log rotation functionality that creates log files
+ * with timestamp-based naming on each startup and automatically cleans up old log files
+ * based on the configured retention period. It ensures that log storage doesn't grow
+ * indefinitely while maintaining a configurable history of log files for debugging
+ * and monitoring purposes.
+ *
+ * The log rotator works by:
+ * 1. Creating log files with format: `{logBaseName}.{YYYYMMDD_HHmmSSZZZ}.log` on each startup
+ * 2. Automatically cleaning up log files older than the configured retention period
+ * 3. Providing utilities to retrieve and manage existing log files
+ *
+ * @example
+ * ```typescript
+ * const logDir = path.join(os.homedir(), '.mcp-hub-lite', 'logs');
+ * const rotator = new LogRotator(logDir, 'mcp-hub');
+ *
+ * // Create a new log file with timestamp (for startup)
+ * const newLogPath = rotator.createNewLogFilePath();
+ *
+ * // Get the latest existing log file
+ * const latestLogPath = rotator.getLatestLogFilePath();
+ *
+ * // Perform log rotation (cleanup old files)
+ * rotator.rotateLogs();
+ *
+ * // Get all log files sorted by date (newest first)
+ * const logFiles = rotator.getLogFiles();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom configuration (independent from global config)
+ * const rotator = new LogRotator(logDir, 'dev-server', { rotationAge: '7d' });
+ * ```
+ *
+ * @class
+ * @since 1.0.0
+ */
+export declare class LogRotator {
+    private logDir;
+    private logBaseName;
+    private customConfig;
+    private configGetter;
+    /**
+     * Creates a new LogRotator instance.
+     *
+     * @param logDir - The directory where log files are stored
+     * @param logBaseName - The base name for log files (default: 'mcp-hub')
+     * @param customConfig - Optional custom configuration for independent rotation settings
+     * @param configGetter - Optional config getter function for global config access (for backward compatibility)
+     */
+    constructor(logDir: string, logBaseName?: string, customConfig?: RotatorConfig, configGetter?: ConfigGetter);
+    /**
+     * Calculates the retention period in days from the configured rotation age.
+     *
+     * Parses the rotation age configuration value which can be in
+     * various formats (e.g., "7d", "24h", "1440m") and converts it to days.
+     * Hours and minutes are converted to days using ceiling division to ensure
+     * proper retention behavior.
+     *
+     * If a customConfig was provided, it will be used; otherwise, falls back to
+     * the configGetter if provided; defaults to 7 days.
+     *
+     * @returns {number} The retention period in days. Defaults to 7 days if the
+     *                   configuration is invalid or cannot be parsed.
+     * @private
+     */
+    private getRetentionDays;
+    /**
+     * Generates a timestamp string in YYYYMMDD_HHmmSSZZZ format.
+     *
+     * @param date - The date to format, defaults to current date/time
+     * @returns {string} Formatted timestamp string
+     * @private
+     */
+    private formatTimestamp;
+    /**
+     * Creates a new log file path with the current timestamp.
+     *
+     * This method generates a log file path using the configured log directory and base name,
+     * combined with the current timestamp in YYYYMMDD_HHmmSSZZZ format. The resulting path
+     * follows the pattern: `{logDir}/{logBaseName}.{YYYYMMDD_HHmmSSZZZ}.log`
+     *
+     * This method should be called on application startup to create a new log file
+     * for each session.
+     *
+     * @returns {string} The absolute file path for the new log file.
+     * @example
+     * ```typescript
+     * const rotator = new LogRotator('/var/log/mcp-hub', 'mcp-hub');
+     * const logPath = rotator.createNewLogFilePath();
+     * // Returns: '/var/log/mcp-hub/mcp-hub.20260301_143022123.log' (with current timestamp)
+     * ```
+     */
+    createNewLogFilePath(): string;
+    /**
+     * Gets the latest existing log file path.
+     *
+     * This method scans the log directory and returns the path to the most recent
+     * log file based on the timestamp in the filename. If no log files exist,
+     * it returns null.
+     *
+     * @returns {string | null} The absolute file path to the latest log file, or null if none exist.
+     * @example
+     * ```typescript
+     * const rotator = new LogRotator('/var/log/mcp-hub', 'mcp-hub');
+     * const latestLog = rotator.getLatestLogFilePath();
+     * // Returns: '/var/log/mcp-hub/mcp-hub.20260301_143022123.log' or null
+     * ```
+     */
+    getLatestLogFilePath(): string | null;
+    /**
+     * Gets the current log file path (backward compatibility).
+     *
+     * This method is maintained for backward compatibility. It first tries to get
+     * the latest existing log file. If none exists, it creates a new one.
+     *
+     * @returns {string} The absolute file path for the current log file.
+     * @deprecated Use createNewLogFilePath() or getLatestLogFilePath() instead
+     * @example
+     * ```typescript
+     * const rotator = new LogRotator('/var/log/mcp-hub', 'mcp-hub');
+     * const logPath = rotator.getCurrentLogFilePath();
+     * ```
+     */
+    getCurrentLogFilePath(): string;
+    /**
+     * Performs log rotation by cleaning up old log files beyond the retention period.
+     *
+     * This method scans the configured log directory for files matching the pattern
+     * `{logBaseName}.{YYYY-MM-DD}.log` and removes any files that are older than
+     * the configured retention period (specified in the system configuration under
+     * `system.logging.rotationAge`).
+     *
+     * The retention period supports various time units:
+     * - 'd' for days (e.g., "7d" = 7 days)
+     * - 'h' for hours (e.g., "24h" = 1 day)
+     * - 'm' for minutes (e.g., "1440m" = 1 day)
+     *
+     * If no valid retention period is configured, it defaults to 7 days.
+     *
+     * This method should be called periodically (e.g., on application startup or
+     * via a scheduled task) to prevent log files from consuming excessive disk space.
+     *
+     * @returns {void}
+     * @throws {Error} If there's an error reading the log directory or deleting files,
+     *                 the error is caught and logged to console.error, but the method
+     *                 continues execution without throwing.
+     * @example
+     * ```typescript
+     * const rotator = new LogRotator('/var/log/mcp-hub', 'mcp-hub');
+     * rotator.rotateLogs(); // Cleans up log files older than configured retention period
+     * ```
+     */
+    rotateLogs(): void;
+    /**
+     * Retrieves all existing log files sorted by date (newest first).
+     *
+     * This method scans the configured log directory for files matching the pattern
+     * `{logBaseName}.{YYYY-MM-DD}.log`, extracts the date from each filename,
+     * and returns an array of absolute file paths sorted in descending order by date
+     * (newest files first).
+     *
+     * This is useful for log management interfaces, log viewing utilities, or any
+     * functionality that needs to present log files in chronological order.
+     *
+     * @returns {string[]} Array of absolute file paths to log files, sorted by date
+     *                     with newest files first. Returns an empty array if no log
+     *                     files are found or if an error occurs during scanning.
+     * @throws {Error} If there's an error reading the log directory, the error is
+     *                 caught and logged to console.error, but the method returns
+     *                 an empty array instead of throwing.
+     * @example
+     * ```typescript
+     * const rotator = new LogRotator('/var/log/mcp-hub', 'mcp-hub');
+     * const logFiles = rotator.getLogFiles();
+     * // Returns: [
+     * //   '/var/log/mcp-hub/mcp-hub.2026-02-16.log',
+     * //   '/var/log/mcp-hub/mcp-hub.2026-02-15.log',
+     * //   '/var/log/mcp-hub/mcp-hub.2026-02-14.log'
+     * // ]
+     * ```
+     */
+    getLogFiles(): string[];
+    /**
+     * Extracts the date from a log filename.
+     *
+     * Parses filenames that match either:
+     * - New format: `{logBaseName}.{YYYYMMDD_HHmmSSZZZ}.log` (preferred)
+     * - Old format: `{logBaseName}.{YYYY-MM-DD}.log` (for backward compatibility)
+     *
+     * and extracts the date portion, converting it to a Date object.
+     *
+     * @param {string} filename - The log filename to parse
+     *                             (e.g., "mcp-hub.20260301_143022123.log" or "mcp-hub.2026-02-16.log")
+     * @returns {Date | null} A Date object representing the extracted date, or null
+     *                        if the filename doesn't match the expected pattern or
+     *                        contains an invalid date.
+     * @private
+     */
+    private extractDateFromFilename;
+}
+export {};
+//# sourceMappingURL=log-rotator.d.ts.map

package/dist/server/src/utils/log-rotator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-rotator.d.ts","sourceRoot":"","sources":["../../../../src/utils/log-rotator.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,KAAK,YAAY,GAAG,MAAM;IAAE,MAAM,EAAE;QAAE,OAAO,EAAE;YAAE,WAAW,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAA;CAAE,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,YAAY,CAAsB;IAE1C;;;;;;;OAOG;gBAED,MAAM,EAAE,MAAM,EACd,WAAW,GAAE,MAAkB,EAC/B,YAAY,CAAC,EAAE,aAAa,EAC5B,YAAY,CAAC,EAAE,YAAY;IAa7B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,gBAAgB;IAwBxB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAWvB;;;;;;;;;;;;;;;;;OAiBG;IACI,oBAAoB,IAAI,MAAM;IAKrC;;;;;;;;;;;;;;OAcG;IACI,oBAAoB,IAAI,MAAM,GAAG,IAAI;IAK5C;;;;;;;;;;;;;OAaG;IACI,qBAAqB,IAAI,MAAM;IAKtC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACI,UAAU,IAAI,IAAI;IAwBzB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACI,WAAW,IAAI,MAAM,EAAE;IAqB9B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,uBAAuB;CA8BhC"}