@machina.ai/openapi-contract-tester 2.1.0

package/dist/utils/logger.js

@@ -0,0 +1,325 @@
+/**
+ * Centralized Logger for OpenAPI Contract Tester
+ *
+ * Provides robust logging with support for:
+ * - MCP mode (writes to file, not stdout/stderr to avoid breaking STDIO protocol)
+ * - Standalone mode (uses console for development/testing)
+ * - Log levels (DEBUG, INFO, WARN, ERROR)
+ * - Structured logging (JSON format)
+ * - Automatic log rotation
+ *
+ * @module utils/logger
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { config } from './config.js';
+/**
+ * Log levels in order of severity
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+})(LogLevel || (LogLevel = {}));
+/**
+ * Centralized logger for the application
+ *
+ * @example
+ * ```typescript
+ * // Initialize for MCP mode (no console output)
+ * const logger = new Logger({
+ *   useConsole: false,
+ *   writeToFile: true,
+ *   minLevel: LogLevel.INFO
+ * });
+ *
+ * // Log messages
+ * logger.info('Server started', { port: 3000 });
+ * logger.error('Failed to parse spec', { error, file: 'api.yml' });
+ *
+ * // Log with source
+ * logger.warn('Endpoint not found', { endpoint: 'POST /users' }, 'business-rules-generator');
+ * ```
+ */
+export class Logger {
+    config;
+    currentLogFile = null;
+    currentLogSize = 0;
+    constructor(config = {}) {
+        this.config = {
+            minLevel: config.minLevel ?? LogLevel.INFO,
+            logDir: config.logDir ?? './logs',
+            logFileName: config.logFileName ?? 'mcp-server',
+            maxFileSize: config.maxFileSize ?? 10 * 1024 * 1024, // 10MB
+            maxFiles: config.maxFiles ?? 5,
+            useConsole: config.useConsole ?? true,
+            writeToFile: config.writeToFile ?? false,
+            includeSource: config.includeSource ?? true,
+        };
+        // Create log directory if it doesn't exist
+        if (this.config.writeToFile) {
+            this.ensureLogDirectory();
+            this.currentLogFile = this.getLogFilePath();
+        }
+    }
+    /**
+     * Logs a debug message
+     *
+     * @param message - Log message
+     * @param meta - Optional metadata
+     * @param source - Optional source component
+     */
+    debug(message, meta, source) {
+        this.log(LogLevel.DEBUG, 'debug', message, meta, source);
+    }
+    /**
+     * Logs an info message
+     *
+     * @param message - Log message
+     * @param meta - Optional metadata
+     * @param source - Optional source component
+     */
+    info(message, meta, source) {
+        this.log(LogLevel.INFO, 'info', message, meta, source);
+    }
+    /**
+     * Logs a warning message
+     *
+     * @param message - Log message
+     * @param meta - Optional metadata
+     * @param source - Optional source component
+     */
+    warn(message, meta, source) {
+        this.log(LogLevel.WARN, 'warn', message, meta, source);
+    }
+    /**
+     * Logs an error message
+     *
+     * @param message - Log message
+     * @param meta - Optional metadata (can include Error object)
+     * @param source - Optional source component
+     */
+    error(message, meta, source) {
+        this.log(LogLevel.ERROR, 'error', message, meta, source);
+    }
+    /**
+     * Core logging method
+     * @internal
+     */
+    log(level, levelName, message, meta, source) {
+        // Check if we should log this level
+        if (level < this.config.minLevel) {
+            return;
+        }
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level: levelName,
+            message,
+        };
+        if (meta !== undefined) {
+            // Serialize Error objects properly
+            if (meta instanceof Error) {
+                entry.meta = {
+                    name: meta.name,
+                    message: meta.message,
+                    stack: meta.stack,
+                };
+            }
+            else {
+                entry.meta = meta;
+            }
+        }
+        if (source && this.config.includeSource) {
+            entry.source = source;
+        }
+        // Write to console if enabled
+        if (this.config.useConsole) {
+            this.writeToConsole(levelName, entry);
+        }
+        // Write to file if enabled
+        if (this.config.writeToFile && this.currentLogFile) {
+            this.writeToFile(entry);
+        }
+    }
+    /**
+     * Writes log entry to console (for standalone mode)
+     * @internal
+     */
+    writeToConsole(level, entry) {
+        const prefix = `[${entry.timestamp}] [${level.toUpperCase()}]${entry.source ? ` [${entry.source}]` : ''}`;
+        const message = `${prefix} ${entry.message}`;
+        if (level === 'error') {
+            console.error(message, entry.meta || '');
+        }
+        else if (level === 'warn') {
+            console.warn(message, entry.meta || '');
+        }
+        else {
+            console.log(message, entry.meta || '');
+        }
+    }
+    /**
+     * Writes log entry to file (for MCP mode)
+     * @internal
+     */
+    writeToFile(entry) {
+        if (!this.currentLogFile)
+            return;
+        try {
+            const line = JSON.stringify(entry) + '\n';
+            const lineSize = Buffer.byteLength(line, 'utf8');
+            // Check if we need to rotate
+            if (this.currentLogSize + lineSize > this.config.maxFileSize) {
+                this.rotateLogFile();
+            }
+            // Append to current log file
+            fs.appendFileSync(this.currentLogFile, line, 'utf8');
+            this.currentLogSize += lineSize;
+        }
+        catch (error) {
+            // Fallback to stderr only if writing to file fails
+            // This won't break MCP protocol as it's an exceptional case
+            if (error instanceof Error) {
+                process.stderr.write(`Logger error: ${error.message}\n`);
+            }
+        }
+    }
+    /**
+     * Ensures log directory exists
+     * @internal
+     */
+    ensureLogDirectory() {
+        if (!fs.existsSync(this.config.logDir)) {
+            fs.mkdirSync(this.config.logDir, { recursive: true });
+        }
+    }
+    /**
+     * Gets the current log file path
+     * @internal
+     */
+    getLogFilePath() {
+        const date = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
+        return path.join(this.config.logDir, `${this.config.logFileName}-${date}.log`);
+    }
+    /**
+     * Rotates log files when max size is reached
+     * @internal
+     */
+    rotateLogFile() {
+        if (!this.currentLogFile)
+            return;
+        try {
+            // Rename current file with timestamp
+            const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+            const rotatedFile = this.currentLogFile.replace('.log', `-${timestamp}.log`);
+            if (fs.existsSync(this.currentLogFile)) {
+                fs.renameSync(this.currentLogFile, rotatedFile);
+            }
+            // Clean up old log files (keep only maxFiles)
+            this.cleanupOldLogs();
+            // Reset current log file
+            this.currentLogFile = this.getLogFilePath();
+            this.currentLogSize = 0;
+        }
+        catch (error) {
+            // Log rotation failure - continue with current file
+            if (error instanceof Error) {
+                process.stderr.write(`Log rotation error: ${error.message}\n`);
+            }
+        }
+    }
+    /**
+     * Removes old log files beyond maxFiles limit
+     * @internal
+     */
+    cleanupOldLogs() {
+        try {
+            const files = fs.readdirSync(this.config.logDir)
+                .filter(f => f.startsWith(this.config.logFileName) && f.endsWith('.log'))
+                .map(f => ({
+                name: f,
+                path: path.join(this.config.logDir, f),
+                mtime: fs.statSync(path.join(this.config.logDir, f)).mtime.getTime()
+            }))
+                .sort((a, b) => b.mtime - a.mtime); // newest first
+            // Remove files beyond maxFiles limit
+            const filesToRemove = files.slice(this.config.maxFiles);
+            for (const file of filesToRemove) {
+                fs.unlinkSync(file.path);
+            }
+        }
+        catch (error) {
+            // Cleanup failure - not critical, just log to stderr
+            if (error instanceof Error) {
+                process.stderr.write(`Log cleanup error: ${error.message}\n`);
+            }
+        }
+    }
+    /**
+     * Flushes any pending logs (useful before shutdown)
+     */
+    flush() {
+        // In this implementation, logs are written synchronously,
+        // so there's nothing to flush. This method is provided for
+        // API compatibility in case we add async logging later.
+    }
+}
+/**
+ * Map config log level to LogLevel enum
+ */
+function mapLogLevel(level) {
+    switch (level) {
+        case 'debug':
+            return LogLevel.DEBUG;
+        case 'info':
+            return LogLevel.INFO;
+        case 'warn':
+            return LogLevel.WARN;
+        case 'error':
+            return LogLevel.ERROR;
+        default:
+            return LogLevel.INFO;
+    }
+}
+/**
+ * Global logger instance
+ *
+ * Configured from environment variables via config module:
+ * - MCP_MODE: Enable file logging (auto-detected from STDIO)
+ * - LOG_LEVEL: Minimum log level (debug, info, warn, error)
+ * - LOG_DIR or MCP_ROOT/logs: Log directory
+ * - MAX_LOG_FILE_SIZE: Maximum file size before rotation (bytes)
+ * - MAX_LOG_FILES: Number of rotated files to keep
+ */
+export const logger = new Logger({
+    useConsole: !config.mcpMode,
+    writeToFile: config.mcpMode,
+    minLevel: mapLogLevel(config.log.level),
+    logDir: config.log.logDir,
+    maxFileSize: config.log.maxFileSize,
+    maxFiles: config.log.maxFiles,
+});
+/**
+ * Creates a logger with a specific source tag
+ *
+ * @param source - Source component name
+ * @returns Logger wrapper with source pre-set
+ *
+ * @example
+ * ```typescript
+ * const log = createLogger('business-rules-generator');
+ * log.info('Processing rules', { count: 20 });
+ * // Output: [2025-01-19T10:00:00Z] [INFO] [business-rules-generator] Processing rules
+ * ```
+ */
+export function createLogger(source) {
+    return {
+        debug: (message, meta) => logger.debug(message, meta, source),
+        info: (message, meta) => logger.info(message, meta, source),
+        warn: (message, meta) => logger.warn(message, meta, source),
+        error: (message, meta) => logger.error(message, meta, source),
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;GAEG;AACH,MAAM,CAAN,IAAY,QAKX;AALD,WAAY,QAAQ;IAClB,yCAAS,CAAA;IACT,uCAAQ,CAAA;IACR,uCAAQ,CAAA;IACR,yCAAS,CAAA;AACX,CAAC,EALW,QAAQ,KAAR,QAAQ,QAKnB;AAsFD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,MAAM;IACT,MAAM,CAAyB;IAC/B,cAAc,GAAkB,IAAI,CAAC;IACrC,cAAc,GAAG,CAAC,CAAC;IAE3B,YAAY,SAAuB,EAAE;QACnC,IAAI,CAAC,MAAM,GAAG;YACZ,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI;YAC1C,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,QAAQ;YACjC,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,YAAY;YAC/C,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,OAAO;YAC5D,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,CAAC;YAC9B,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,IAAI;YACrC,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,KAAK;YACxC,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,IAAI;SAC5C,CAAC;QAEF,2CAA2C;QAC3C,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YAC5B,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC1B,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QAC9C,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAe,EAAE,IAAc,EAAE,MAAe;QACpD,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,OAAe,EAAE,IAAc,EAAE,MAAe;QACnD,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACzD,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,OAAe,EAAE,IAAc,EAAE,MAAe;QACnD,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACzD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAe,EAAE,IAAc,EAAE,MAAe;QACpD,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3D,CAAC;IAED;;;OAGG;IACK,GAAG,CACT,KAAe,EACf,SAA8C,EAC9C,OAAe,EACf,IAAc,EACd,MAAe;QAEf,oCAAoC;QACpC,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACjC,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAa;YACtB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,KAAK,EAAE,SAAS;YAChB,OAAO;SACR,CAAC;QAEF,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,mCAAmC;YACnC,IAAI,IAAI,YAAY,KAAK,EAAE,CAAC;gBAC1B,KAAK,CAAC,IAAI,GAAG;oBACX,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,OAAO,EAAE,IAAI,CAAC,OAAO;oBACrB,KAAK,EAAE,IAAI,CAAC,KAAK;iBAClB,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;YACpB,CAAC;QACH,CAAC;QAED,IAAI,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;YACxC,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;QACxB,CAAC;QAED,8BAA8B;QAC9B,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;YAC3B,IAAI,CAAC,cAAc,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QACxC,CAAC;QAED,2BAA2B;QAC3B,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACnD,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,cAAc,CACpB,KAA0C,EAC1C,KAAe;QAEf,MAAM,MAAM,GAAG,IAAI,KAAK,CAAC,SAAS,MAAM,KAAK,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QAC1G,MAAM,OAAO,GAAG,GAAG,MAAM,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAE7C,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;YACtB,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;QAC3C,CAAC;aAAM,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;QAC1C,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,WAAW,CAAC,KAAe;QACjC,IAAI,CAAC,IAAI,CAAC,cAAc;YAAE,OAAO;QAEjC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;YAC1C,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAEjD,6BAA6B;YAC7B,IAAI,IAAI,CAAC,cAAc,GAAG,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;gBAC7D,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,CAAC;YAED,6BAA6B;YAC7B,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YACrD,IAAI,CAAC,cAAc,IAAI,QAAQ,CAAC;QAClC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,mDAAmD;YACnD,4DAA4D;YAC5D,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;gBAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,kBAAkB;QACxB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YACvC,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,cAAc;QACpB,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa;QAClE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,IAAI,IAAI,MAAM,CAAC,CAAC;IACjF,CAAC;IAED;;;OAGG;IACK,aAAa;QACnB,IAAI,CAAC,IAAI,CAAC,cAAc;YAAE,OAAO;QAEjC,IAAI,CAAC;YACH,qCAAqC;YACrC,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YACjE,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,SAAS,MAAM,CAAC,CAAC;YAE7E,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;gBACvC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;YAClD,CAAC;YAED,8CAA8C;YAC9C,IAAI,CAAC,cAAc,EAAE,CAAC;YAEtB,yBAAyB;YACzB,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;YAC5C,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,oDAAoD;YACpD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;gBAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;YACjE,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;OAGG;IACK,cAAc;QACpB,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;iBAC7C,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;iBACxE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBACT,IAAI,EAAE,CAAC;gBACP,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;gBACtC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE;aACrE,CAAC,CAAC;iBACF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,eAAe;YAErD,qCAAqC;YACrC,MAAM,aAAa,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YACxD,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;gBACjC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,qDAAqD;YACrD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;gBAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,sBAAsB,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;YAChE,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK;QACH,0DAA0D;QAC1D,2DAA2D;QAC3D,wDAAwD;IAC1D,CAAC;CACF;AAED;;GAEG;AACH,SAAS,WAAW,CAAC,KAAa;IAChC,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,OAAO;YACV,OAAO,QAAQ,CAAC,KAAK,CAAC;QACxB,KAAK,MAAM;YACT,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,KAAK,MAAM;YACT,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,KAAK,OAAO;YACV,OAAO,QAAQ,CAAC,KAAK,CAAC;QACxB;YACE,OAAO,QAAQ,CAAC,IAAI,CAAC;IACzB,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC;IAC/B,UAAU,EAAE,CAAC,MAAM,CAAC,OAAO;IAC3B,WAAW,EAAE,MAAM,CAAC,OAAO;IAC3B,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM;IACzB,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,WAAW;IACnC,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,QAAQ;CAC9B,CAAC,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,OAAO;QACL,KAAK,EAAE,CAAC,OAAe,EAAE,IAAc,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC;QAC/E,IAAI,EAAE,CAAC,OAAe,EAAE,IAAc,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC;QAC7E,IAAI,EAAE,CAAC,OAAe,EAAE,IAAc,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC;QAC7E,KAAK,EAAE,CAAC,OAAe,EAAE,IAAc,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC;KAChF,CAAC;AACJ,CAAC"}

package/dist/utils/openapi-discovery.d.ts

@@ -0,0 +1,31 @@
+/**
+ * OpenAPI Auto-Discovery Utility
+ *
+ * Automatically discovers OpenAPI specifications from a base URL by:
+ * 1. Trying common paths (fast)
+ * 2. Using AI to extract from documentation (slower, more comprehensive)
+ *
+ * @module utils/openapi-discovery
+ */
+/**
+ * Attempts to discover OpenAPI specification from a base URL
+ *
+ * @param baseUrl - Base URL of the API
+ * @returns OpenAPI spec content or null if not found
+ */
+export declare function discoverOpenAPI(baseUrl: string): Promise<string | null>;
+/**
+ * Tries to fetch OpenAPI spec from common paths
+ *
+ * @param baseUrl - Base URL of the API
+ * @returns OpenAPI spec content or null
+ */
+export declare function tryCommonPaths(baseUrl: string): Promise<string | null>;
+/**
+ * Attempts to extract OpenAPI spec from documentation pages using AI
+ *
+ * @param baseUrl - Base URL of the API
+ * @returns OpenAPI spec content or null
+ */
+export declare function extractFromDocs(baseUrl: string): Promise<string | null>;
+//# sourceMappingURL=openapi-discovery.d.ts.map

package/dist/utils/openapi-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-discovery.d.ts","sourceRoot":"","sources":["../../src/utils/openapi-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgDH;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiB7E;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA8C5E;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAkD7E"}

package/dist/utils/openapi-discovery.js

@@ -0,0 +1,322 @@
+/**
+ * OpenAPI Auto-Discovery Utility
+ *
+ * Automatically discovers OpenAPI specifications from a base URL by:
+ * 1. Trying common paths (fast)
+ * 2. Using AI to extract from documentation (slower, more comprehensive)
+ *
+ * @module utils/openapi-discovery
+ */
+import { callLLM } from '../llm/ai-client.js';
+import { createLogger } from './logger.js';
+const log = createLogger('openapi-discovery');
+/**
+ * Common paths where OpenAPI specs are typically located
+ */
+const COMMON_SPEC_PATHS = [
+    '/openapi.json',
+    '/openapi.yaml',
+    '/swagger.json',
+    '/swagger.yaml',
+    '/api-docs',
+    '/api-docs.json',
+    '/api-docs.yaml',
+    '/docs/openapi.json',
+    '/docs/openapi.yaml',
+    '/docs/swagger.json',
+    '/docs/swagger.yaml',
+    '/v1/openapi.json',
+    '/v1/swagger.json',
+    '/v2/openapi.json',
+    '/v3/openapi.json',
+    '/api/openapi.json',
+    '/api/swagger.json',
+    '/.well-known/api-docs',
+    '/.well-known/openapi.json',
+    '/redoc/openapi.json',
+    '/swagger-ui/openapi.json'
+];
+/**
+ * Common documentation paths to check
+ */
+const COMMON_DOC_PATHS = [
+    '/docs',
+    '/api-docs',
+    '/documentation',
+    '/swagger-ui',
+    '/swagger',
+    '/redoc',
+    '/api/docs',
+    '/api/documentation'
+];
+/**
+ * Attempts to discover OpenAPI specification from a base URL
+ *
+ * @param baseUrl - Base URL of the API
+ * @returns OpenAPI spec content or null if not found
+ */
+export async function discoverOpenAPI(baseUrl) {
+    log.info('Starting OpenAPI auto-discovery', { baseUrl });
+    // Phase 1: Try common paths (fast)
+    const specFromCommonPath = await tryCommonPaths(baseUrl);
+    if (specFromCommonPath) {
+        return specFromCommonPath;
+    }
+    // Phase 2: Try to extract from documentation (slower)
+    const specFromDocs = await extractFromDocs(baseUrl);
+    if (specFromDocs) {
+        return specFromDocs;
+    }
+    log.warn('OpenAPI spec not found', { baseUrl });
+    return null;
+}
+/**
+ * Tries to fetch OpenAPI spec from common paths
+ *
+ * @param baseUrl - Base URL of the API
+ * @returns OpenAPI spec content or null
+ */
+export async function tryCommonPaths(baseUrl) {
+    log.info('Trying common OpenAPI paths', { baseUrl, pathCount: COMMON_SPEC_PATHS.length });
+    // Ensure baseUrl doesn't end with slash
+    const cleanBaseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+    for (const path of COMMON_SPEC_PATHS) {
+        try {
+            const url = cleanBaseUrl + path;
+            log.debug('Attempting to fetch spec', { url });
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 5000);
+            const response = await fetch(url, {
+                method: 'GET',
+                headers: {
+                    'Accept': 'application/json, application/yaml, application/x-yaml, text/yaml, text/x-yaml'
+                },
+                signal: controller.signal
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                const content = await response.text();
+                // Validate that it looks like an OpenAPI spec
+                if (isValidOpenAPISpec(content)) {
+                    log.info('OpenAPI spec discovered', { url, size: content.length });
+                    return content;
+                }
+                else {
+                    log.debug('Invalid OpenAPI spec format', { url });
+                }
+            }
+        }
+        catch (error) {
+            // Ignore errors, try next path
+            log.debug('Failed to fetch spec', {
+                path,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    log.info('No OpenAPI spec found in common paths');
+    return null;
+}
+/**
+ * Attempts to extract OpenAPI spec from documentation pages using AI
+ *
+ * @param baseUrl - Base URL of the API
+ * @returns OpenAPI spec content or null
+ */
+export async function extractFromDocs(baseUrl) {
+    log.info('Attempting to extract OpenAPI from documentation', { baseUrl });
+    const cleanBaseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+    // Try to fetch documentation pages
+    for (const docPath of COMMON_DOC_PATHS) {
+        try {
+            const url = cleanBaseUrl + docPath;
+            log.debug('Fetching documentation page', { url });
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), 5000);
+            const response = await fetch(url, {
+                method: 'GET',
+                headers: {
+                    'Accept': 'text/html, application/xhtml+xml'
+                },
+                signal: controller.signal
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                const html = await response.text();
+                // Check if the HTML contains references to OpenAPI spec
+                const specUrl = extractSpecUrlFromHTML(html, cleanBaseUrl);
+                if (specUrl) {
+                    log.info('Found OpenAPI spec URL in docs', { specUrl });
+                    return await fetchSpec(specUrl);
+                }
+                // If no direct URL found, try to extract with AI
+                const extractedSpec = await extractSpecWithAI(html, baseUrl);
+                if (extractedSpec) {
+                    return extractedSpec;
+                }
+            }
+        }
+        catch (error) {
+            log.debug('Failed to fetch documentation', {
+                docPath,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    log.info('Could not extract OpenAPI from documentation');
+    return null;
+}
+/**
+ * Extracts OpenAPI spec URL from HTML content
+ *
+ * @param html - HTML content
+ * @param baseUrl - Base URL for resolving relative URLs
+ * @returns OpenAPI spec URL or null
+ */
+function extractSpecUrlFromHTML(html, baseUrl) {
+    // Common patterns in Swagger UI and ReDoc
+    const patterns = [
+        /url:\s*["']([^"']+)["']/,
+        /spec-url:\s*["']([^"']+)["']/,
+        /spec:\s*["']([^"']+)["']/,
+        /data-spec-url=["']([^"']+)["']/,
+        /"specUrl":\s*["']([^"']+)["']/,
+        /"spec":\s*["']([^"']+)["']/
+    ];
+    for (const pattern of patterns) {
+        const match = html.match(pattern);
+        if (match && match[1]) {
+            const specUrl = match[1];
+            // Resolve relative URLs
+            if (specUrl.startsWith('http')) {
+                return specUrl;
+            }
+            else if (specUrl.startsWith('/')) {
+                return baseUrl + specUrl;
+            }
+            else {
+                return baseUrl + '/' + specUrl;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Fetches OpenAPI spec from a URL
+ *
+ * @param url - URL of the spec
+ * @returns Spec content or null
+ */
+async function fetchSpec(url) {
+    try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 5000);
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                'Accept': 'application/json, application/yaml'
+            },
+            signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (response.ok) {
+            const content = await response.text();
+            if (isValidOpenAPISpec(content)) {
+                return content;
+            }
+        }
+    }
+    catch (error) {
+        log.debug('Failed to fetch spec', {
+            url,
+            error: error instanceof Error ? error.message : String(error)
+        });
+    }
+    return null;
+}
+/**
+ * Uses AI to extract API endpoints from documentation and generate OpenAPI spec
+ *
+ * @param html - HTML documentation content
+ * @param baseUrl - Base URL of the API
+ * @returns Generated OpenAPI spec or null
+ */
+async function extractSpecWithAI(html, baseUrl) {
+    try {
+        // Truncate HTML to avoid token limits (first 10000 chars)
+        const truncatedHtml = html.slice(0, 10000);
+        const prompt = `Extract API endpoints from this HTML documentation and generate a basic OpenAPI 3.0 specification.
+
+Base URL: ${baseUrl}
+
+HTML Documentation (truncated):
+${truncatedHtml}
+
+Generate a valid OpenAPI 3.0 JSON specification with:
+- info.title (extract from HTML)
+- info.version (use "1.0.0" if not found)
+- paths with methods (GET, POST, PUT, DELETE, etc.)
+- basic request/response schemas (if visible in docs)
+
+Respond with ONLY valid JSON in OpenAPI 3.0 format. Do not include explanations or markdown.`;
+        log.info('Attempting AI extraction from documentation');
+        const result = await callLLM(prompt, {
+            maxTokens: 4096,
+            temperature: 0.2,
+            timeout: 30000
+        });
+        if (!result.success || !result.text) {
+            log.warn('AI extraction failed', { error: result.error });
+            return null;
+        }
+        // Clean the response (remove markdown code blocks if present)
+        let cleanedText = result.text.trim();
+        if (cleanedText.startsWith('```')) {
+            cleanedText = cleanedText.replace(/^```(?:json)?\n/, '').replace(/\n```$/, '');
+        }
+        // Validate JSON
+        try {
+            JSON.parse(cleanedText);
+            log.info('AI successfully extracted OpenAPI spec', { size: cleanedText.length });
+            return cleanedText;
+        }
+        catch (parseError) {
+            log.warn('AI generated invalid JSON', { parseError });
+            return null;
+        }
+    }
+    catch (error) {
+        log.error('AI extraction error', {
+            error: error instanceof Error ? error.message : String(error)
+        });
+        return null;
+    }
+}
+/**
+ * Validates if content looks like a valid OpenAPI specification
+ *
+ * @param content - Content to validate
+ * @returns true if content appears to be OpenAPI spec
+ */
+function isValidOpenAPISpec(content) {
+    try {
+        // Try to parse as JSON
+        const parsed = JSON.parse(content);
+        // Check for OpenAPI indicators
+        if (parsed.openapi && parsed.openapi.startsWith('3.')) {
+            return true;
+        }
+        if (parsed.swagger && parsed.swagger.startsWith('2.')) {
+            return true;
+        }
+        return false;
+    }
+    catch {
+        // Not JSON, might be YAML
+        // Check for OpenAPI/Swagger keywords
+        const lowerContent = content.toLowerCase();
+        return ((lowerContent.includes('openapi:') && lowerContent.includes('paths:')) ||
+            (lowerContent.includes('swagger:') && lowerContent.includes('paths:')));
+    }
+}
+//# sourceMappingURL=openapi-discovery.js.map