@codemcp/workflows-core 3.1.16

package/src/logger.ts

@@ -0,0 +1,353 @@
+/**
+ * Logging utility for Vibe Feature MCP Server
+ *
+ * Provides structured logging with proper MCP compliance:
+ * - Uses stderr for all local logging (MCP requirement)
+ * - Supports MCP log message notifications to client
+ * - Provides structured logging with proper levels:
+ *   - debug: Tracing and detailed execution flow
+ *   - info: Success operations and important milestones
+ *   - warn: Expected errors and recoverable issues
+ *   - error: Caught but unexpected errors
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+export enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+  SILENT = 4, // Suppress all logging
+}
+
+export interface LogContext {
+  component?: string;
+  conversationId?: string;
+  phase?: string;
+  operation?: string;
+  [key: string]: unknown;
+}
+
+// Global MCP server reference for log notifications
+let mcpServerInstance: McpServer | null = null;
+
+// Unified logging level - can be set by MCP client or environment
+let currentLoggingLevel: LogLevel | null = null;
+
+// Test mode detection function to check at runtime
+function isTestMode(): boolean {
+  // Check explicit environment variables
+  if (process.env.NODE_ENV === 'test' || process.env.VITEST === 'true') {
+    return true;
+  }
+
+  // Check if running in a temporary directory (common for tests)
+  const cwd = process.cwd();
+  if (cwd.includes('/tmp/') || cwd.includes('temp') || cwd.includes('test-')) {
+    return true;
+  }
+
+  // Check if LOG_LEVEL is explicitly set to ERROR
+  if (process.env.LOG_LEVEL === 'ERROR') {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Set the MCP server instance for log notifications
+ */
+export function setMcpServerForLogging(server: McpServer): void {
+  mcpServerInstance = server;
+}
+
+/**
+ * Set the logging level from MCP client request
+ */
+export function setMcpLoggingLevel(level: string): void {
+  // Map MCP levels to our internal levels
+  const levelMap: Record<string, LogLevel> = {
+    debug: LogLevel.DEBUG,
+    info: LogLevel.INFO,
+    notice: LogLevel.INFO,
+    warning: LogLevel.WARN,
+    error: LogLevel.ERROR,
+    critical: LogLevel.ERROR,
+    alert: LogLevel.ERROR,
+    emergency: LogLevel.ERROR,
+  };
+
+  currentLoggingLevel = levelMap[level] ?? LogLevel.INFO;
+}
+
+class Logger {
+  private component: string;
+  private explicitLogLevel?: LogLevel;
+
+  constructor(component: string, logLevel?: LogLevel) {
+    this.component = component;
+    this.explicitLogLevel = logLevel;
+  }
+
+  private getCurrentLogLevel(): LogLevel {
+    // Check environment variable first (allows SILENT to override test mode)
+    const envLevel = this.getLogLevelFromEnv();
+    if (envLevel === LogLevel.SILENT) {
+      return LogLevel.SILENT;
+    }
+
+    // Force ERROR level in test environments (unless SILENT)
+    if (isTestMode()) {
+      return LogLevel.ERROR;
+    }
+
+    // Use MCP-set level if available (takes precedence)
+    if (currentLoggingLevel !== null) {
+      return currentLoggingLevel;
+    }
+
+    // Use environment variable level
+    if (envLevel !== null) {
+      return envLevel;
+    }
+
+    // If explicit log level was provided, use it
+    if (this.explicitLogLevel !== undefined) {
+      return this.explicitLogLevel;
+    }
+
+    // Default to INFO
+    return LogLevel.INFO;
+  }
+
+  private getLogLevelFromEnv(): LogLevel | null {
+    const envLevel = process.env.LOG_LEVEL?.toUpperCase();
+    switch (envLevel) {
+      case 'DEBUG':
+        return LogLevel.DEBUG;
+      case 'INFO':
+        return LogLevel.INFO;
+      case 'WARN':
+        return LogLevel.WARN;
+      case 'ERROR':
+        return LogLevel.ERROR;
+      case 'SILENT':
+        return LogLevel.SILENT;
+      default:
+        return null;
+    }
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    return level >= this.getCurrentLogLevel();
+  }
+
+  private formatMessage(
+    level: string,
+    message: string,
+    context?: LogContext
+  ): string {
+    const timestamp = new Date().toISOString();
+    const contextStr = context ? ` ${JSON.stringify(context)}` : '';
+    return `[${timestamp}] ${level.toUpperCase()} [${this.component}] ${message}${contextStr}`;
+  }
+
+  /**
+   * Send log message to MCP client if server is available and level is appropriate
+   */
+  private async sendMcpLogMessage(
+    level: 'debug' | 'info' | 'warning' | 'error',
+    message: string,
+    context?: LogContext
+  ): Promise<void> {
+    if (mcpServerInstance) {
+      try {
+        // Safely serialize context to avoid JSON issues
+        let logData = message;
+        if (context) {
+          try {
+            const contextStr = JSON.stringify(context, null, 0);
+            logData = `${message} ${contextStr}`;
+          } catch (_error) {
+            // If JSON serialization fails, just use the message
+            logData = `${message} [context serialization failed]`;
+          }
+        }
+
+        await mcpServerInstance.server.notification({
+          method: 'notifications/message',
+          params: {
+            level,
+            logger: this.component,
+            data: logData,
+          },
+        });
+      } catch (error) {
+        // Fallback to stderr if MCP notification fails
+        // Don't use this.error to avoid infinite recursion
+        if (!isTestMode()) {
+          process.stderr.write(
+            `[MCP-LOG-ERROR] Failed to send log notification: ${error}\n`
+          );
+        }
+      }
+    }
+  }
+
+  debug(message: string, context?: LogContext): void {
+    if (this.shouldLog(LogLevel.DEBUG)) {
+      const formattedMessage = this.formatMessage('debug', message, context);
+      // Always log to stderr for MCP compliance
+      process.stderr.write(formattedMessage + '\n');
+      // Also send to MCP client if available (only for debug level)
+      this.sendMcpLogMessage('debug', message, context).catch(() => {
+        // Ignore MCP notification errors for debug messages
+      });
+    }
+  }
+
+  info(message: string, context?: LogContext): void {
+    if (this.shouldLog(LogLevel.INFO)) {
+      const formattedMessage = this.formatMessage('info', message, context);
+      // Always log to stderr for MCP compliance
+      process.stderr.write(formattedMessage + '\n');
+
+      // Send enhanced notifications for important events
+      this.sendEnhancedMcpNotification('info', message, context).catch(() => {
+        // Ignore MCP notification errors for info messages
+      });
+    }
+  }
+
+  /**
+   * Send enhanced MCP notifications with better formatting for important events
+   */
+  private async sendEnhancedMcpNotification(
+    level: 'debug' | 'info' | 'warning' | 'error',
+    message: string,
+    context?: LogContext
+  ): Promise<void> {
+    if (mcpServerInstance) {
+      try {
+        let enhancedMessage = message;
+        let notificationLevel = level;
+
+        // Enhance phase transition messages
+        if (
+          context &&
+          (context.from || context.to) &&
+          message.includes('transition')
+        ) {
+          const from = context.from
+            ? this.capitalizePhase(context.from as string)
+            : '';
+          const to = context.to
+            ? this.capitalizePhase(context.to as string)
+            : '';
+          if (from && to) {
+            enhancedMessage = `Phase Transition: ${from} → ${to}`;
+            notificationLevel = 'info';
+          }
+        }
+
+        // Enhance initialization messages
+        if (message.includes('initialized successfully')) {
+          enhancedMessage = '🚀 Vibe Feature MCP Server Ready';
+          notificationLevel = 'info';
+        }
+
+        // Safely serialize context to avoid JSON issues
+        let logData = enhancedMessage;
+        if (context) {
+          try {
+            const contextStr = JSON.stringify(context, null, 0);
+            logData = `${enhancedMessage} ${contextStr}`;
+          } catch (_error) {
+            // If JSON serialization fails, just use the message
+            logData = `${enhancedMessage} [context serialization failed]`;
+          }
+        }
+
+        // Use the underlying server's notification method
+        await mcpServerInstance.server.notification({
+          method: 'notifications/message',
+          params: {
+            level: notificationLevel,
+            logger: this.component,
+            data: logData,
+          },
+        });
+      } catch (error) {
+        // Fallback to stderr if MCP notification fails
+        // Don't use this.error to avoid infinite recursion
+        if (!isTestMode()) {
+          process.stderr.write(
+            `[MCP-LOG-ERROR] Failed to send log notification: ${error}\n`
+          );
+        }
+      }
+    }
+  }
+
+  /**
+   * Capitalize phase name for display
+   */
+  private capitalizePhase(phase: string): string {
+    return phase
+      .split('_')
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+  }
+
+  warn(message: string, context?: LogContext): void {
+    if (this.shouldLog(LogLevel.WARN)) {
+      const formattedMessage = this.formatMessage('warn', message, context);
+      // Always log to stderr for MCP compliance
+      process.stderr.write(formattedMessage + '\n');
+      // Also send to MCP client if available
+      this.sendEnhancedMcpNotification('warning', message, context).catch(
+        () => {
+          // Ignore MCP notification errors for warn messages
+        }
+      );
+    }
+  }
+
+  error(message: string, error?: Error, context?: LogContext): void {
+    if (this.shouldLog(LogLevel.ERROR)) {
+      const errorContext = error
+        ? { ...context, error: error.message, stack: error.stack }
+        : context;
+      const formattedMessage = this.formatMessage(
+        'error',
+        message,
+        errorContext
+      );
+      // Always log to stderr for MCP compliance
+      process.stderr.write(formattedMessage + '\n');
+      // Also send to MCP client if available
+      this.sendEnhancedMcpNotification('error', message, errorContext).catch(
+        () => {
+          // Ignore MCP notification errors for error messages
+        }
+      );
+    }
+  }
+
+  child(childComponent: string): Logger {
+    return new Logger(
+      `${this.component}:${childComponent}`,
+      this.explicitLogLevel
+    );
+  }
+}
+
+// Factory function to create loggers
+export function createLogger(component: string, logLevel?: LogLevel): Logger {
+  return new Logger(component, logLevel);
+}
+
+// Default logger for the main application
+export const logger = createLogger('VibeFeatureMCP');

package/src/path-validation-utils.ts

@@ -0,0 +1,261 @@
+/**
+ * Path Validation Utilities
+ *
+ * Provides utilities for validating file paths, resolving relative paths,
+ * and ensuring security constraints for the file linking functionality.
+ */
+
+import { access, stat } from 'node:fs/promises';
+import { resolve, isAbsolute, join, normalize } from 'node:path';
+import { createLogger } from './logger.js';
+
+const logger = createLogger('PathValidationUtils');
+
+export interface PathValidationResult {
+  isValid: boolean;
+  resolvedPath?: string;
+  error?: string;
+}
+
+export class PathValidationUtils {
+  /**
+   * Validate if a string is a known template name
+   */
+  static isTemplateName(value: string, availableTemplates: string[]): boolean {
+    return availableTemplates.includes(value);
+  }
+
+  /**
+   * Validate and resolve a file path
+   */
+  static async validateFilePath(
+    filePath: string,
+    projectPath: string
+  ): Promise<PathValidationResult> {
+    try {
+      // Resolve the path to absolute
+      const resolvedPath = this.resolvePath(filePath, projectPath);
+
+      // Security validation - prevent directory traversal
+      if (!this.isPathSafe(resolvedPath, projectPath)) {
+        return {
+          isValid: false,
+          error: 'Path is outside project boundaries for security reasons',
+        };
+      }
+
+      // Check if file exists and is readable
+      await access(resolvedPath);
+
+      // Verify it's a file (not a directory)
+      const stats = await stat(resolvedPath);
+      if (!stats.isFile()) {
+        return {
+          isValid: false,
+          error: 'Path points to a directory, not a file',
+        };
+      }
+
+      logger.debug('File path validated successfully', {
+        originalPath: filePath,
+        resolvedPath,
+      });
+
+      return {
+        isValid: true,
+        resolvedPath,
+      };
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : 'Unknown error';
+
+      logger.debug('File path validation failed', {
+        filePath,
+        error: errorMessage,
+      });
+
+      return {
+        isValid: false,
+        error: `File not found or not accessible: ${errorMessage}`,
+      };
+    }
+  }
+
+  /**
+   * Validate and resolve a file or directory path
+   */
+  static async validateFileOrDirectoryPath(
+    filePath: string,
+    projectPath: string
+  ): Promise<PathValidationResult> {
+    try {
+      // Resolve the path to absolute
+      const resolvedPath = this.resolvePath(filePath, projectPath);
+
+      // Security validation - prevent directory traversal
+      if (!this.isPathSafe(resolvedPath, projectPath)) {
+        return {
+          isValid: false,
+          error: 'Path is outside project boundaries for security reasons',
+        };
+      }
+
+      // Check if file or directory exists and is readable
+      await access(resolvedPath);
+
+      // Verify it's either a file or directory
+      const stats = await stat(resolvedPath);
+      if (!stats.isFile() && !stats.isDirectory()) {
+        return {
+          isValid: false,
+          error: 'Path is neither a file nor a directory',
+        };
+      }
+
+      logger.debug('File or directory path validated successfully', {
+        originalPath: filePath,
+        resolvedPath,
+        isFile: stats.isFile(),
+        isDirectory: stats.isDirectory(),
+      });
+
+      return {
+        isValid: true,
+        resolvedPath,
+      };
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : 'Unknown error';
+
+      logger.debug('File or directory path validation failed', {
+        filePath,
+        error: errorMessage,
+      });
+
+      return {
+        isValid: false,
+        error: `File or directory not found or not accessible: ${errorMessage}`,
+      };
+    }
+  }
+
+  /**
+   * Resolve a file path to absolute, handling various formats
+   */
+  static resolvePath(filePath: string, projectPath: string): string {
+    // If already absolute, return as-is
+    if (isAbsolute(filePath)) {
+      return normalize(filePath);
+    }
+
+    // Handle relative paths (./file, ../file, file)
+    return resolve(projectPath, filePath);
+  }
+
+  /**
+   * Check if a resolved path is within safe boundaries
+   * Prevents directory traversal attacks
+   */
+  static isPathSafe(resolvedPath: string, projectPath: string): boolean {
+    const normalizedResolved = normalize(resolvedPath);
+    const normalizedProject = normalize(projectPath);
+
+    // Allow paths within the project directory
+    if (normalizedResolved.startsWith(normalizedProject)) {
+      return true;
+    }
+
+    // Allow paths in common documentation locations relative to project
+    const allowedPaths = [
+      normalize(join(projectPath, '..')), // Parent directory (for monorepos)
+      '/usr/share/doc', // System documentation
+      '/opt/docs', // Optional documentation
+    ];
+
+    return allowedPaths.some(allowedPath =>
+      normalizedResolved.startsWith(allowedPath)
+    );
+  }
+
+  /**
+   * Validate parameter as either template name or file path
+   */
+  static async validateParameter(
+    value: string,
+    availableTemplates: string[],
+    projectPath: string
+  ): Promise<{
+    isTemplate: boolean;
+    isFilePath: boolean;
+    resolvedPath?: string;
+    error?: string;
+  }> {
+    // First check if it's a template name
+    if (this.isTemplateName(value, availableTemplates)) {
+      return {
+        isTemplate: true,
+        isFilePath: false,
+      };
+    }
+
+    // Then validate as file or directory path
+    const pathValidation = await this.validateFileOrDirectoryPath(
+      value,
+      projectPath
+    );
+
+    if (pathValidation.isValid) {
+      return {
+        isTemplate: false,
+        isFilePath: true,
+        resolvedPath: pathValidation.resolvedPath,
+      };
+    }
+
+    // Neither template nor valid file/directory path
+    return {
+      isTemplate: false,
+      isFilePath: false,
+      error: `Invalid parameter: not a known template (${availableTemplates.join(', ')}) and not a valid file or directory path (${pathValidation.error})`,
+    };
+  }
+
+  /**
+   * Get common file patterns for documentation
+   */
+  static getCommonDocumentationPatterns(): {
+    architecture: string[];
+    requirements: string[];
+    design: string[];
+  } {
+    return {
+      architecture: [
+        'ARCHITECTURE.md',
+        'ARCHITECTURE.txt',
+        'architecture.md',
+        'Architecture.md',
+        'docs/ARCHITECTURE.md',
+        'docs/architecture.md',
+        'README.md', // Can contain architecture info
+      ],
+      requirements: [
+        'REQUIREMENTS.md',
+        'REQUIREMENTS.txt',
+        'requirements.md',
+        'Requirements.md',
+        'docs/REQUIREMENTS.md',
+        'docs/requirements.md',
+        'README.md', // Often contains requirements
+      ],
+      design: [
+        'DESIGN.md',
+        'DESIGN.txt',
+        'design.md',
+        'Design.md',
+        'docs/DESIGN.md',
+        'docs/design.md',
+        'README.md', // Can contain design info
+      ],
+    };
+  }
+}