mcp-wordpress 2.6.3 → 2.7.0

package/src/client/managers/composed/MigrationAdapter.ts

@@ -0,0 +1,263 @@
+/**
+ * Migration Adapter
+ * Provides backward compatibility while transitioning from inheritance to composition
+ */
+
+import type { WordPressClientConfig, HTTPMethod } from "@/types/client.js";
+import { RequestManager } from "../RequestManager.js";
+import { AuthenticationManager } from "../AuthenticationManager.js";
+import { ComposedRequestManager } from "../ComposedRequestManager.js";
+import { ComposedAuthenticationManager } from "../ComposedAuthenticationManager.js";
+
+/**
+ * Adapter that wraps composed managers to provide the same interface as inheritance-based ones
+ */
+export class RequestManagerAdapter {
+  private composedManager: ComposedRequestManager;
+
+  constructor(clientConfig: WordPressClientConfig, authManager: AuthenticationManager | ComposedAuthenticationManager) {
+    // If the authManager is the old inheritance-based one, create a composed one
+    let composedAuthManager: ComposedAuthenticationManager;
+
+    if (authManager instanceof ComposedAuthenticationManager) {
+      composedAuthManager = authManager;
+    } else {
+      // Create composed auth manager from config
+      composedAuthManager = ComposedAuthenticationManager.create(clientConfig);
+    }
+
+    this.composedManager = ComposedRequestManager.create(clientConfig, composedAuthManager);
+  }
+
+  /**
+   * Initialize the adapter
+   */
+  async initialize(): Promise<void> {
+    await this.composedManager.initialize();
+  }
+
+  /**
+   * Delegate request method to composed manager
+   */
+  async request<T>(method: HTTPMethod, endpoint: string, data?: unknown, options?: unknown): Promise<T> {
+    return this.composedManager.request<T>(
+      method,
+      endpoint,
+      data,
+      options as Parameters<ComposedRequestManager["request"]>[3],
+    );
+  }
+
+  /**
+   * Delegate stats method
+   */
+  getStats(): unknown {
+    return this.composedManager.getStats();
+  }
+
+  /**
+   * Delegate reset stats method
+   */
+  resetStats(): void {
+    this.composedManager.resetStats();
+  }
+
+  /**
+   * Cleanup method
+   */
+  dispose(): void {
+    this.composedManager.dispose();
+  }
+}
+
+/**
+ * Migration utilities for gradual transition
+ */
+export class MigrationAdapter {
+  /**
+   * Create managers using the new composition approach but with backward-compatible interface
+   */
+  static async createCompatibleManagers(config: WordPressClientConfig): Promise<{
+    requestManager: RequestManagerAdapter;
+    authManager: ComposedAuthenticationManager;
+  }> {
+    const authManager = ComposedAuthenticationManager.create(config);
+    await authManager.authenticate();
+
+    const requestManager = new RequestManagerAdapter(config, authManager);
+    await requestManager.initialize();
+
+    return {
+      requestManager,
+      authManager,
+    };
+  }
+
+  /**
+   * Factory method that returns either old or new managers based on feature flag
+   */
+  static async createManagers(
+    config: WordPressClientConfig,
+    useComposition: boolean = true,
+  ): Promise<{
+    requestManager: RequestManager | RequestManagerAdapter;
+    authManager: AuthenticationManager | ComposedAuthenticationManager;
+  }> {
+    if (useComposition) {
+      return MigrationAdapter.createCompatibleManagers(config);
+    } else {
+      // Return old inheritance-based managers (simplified for now)
+      throw new Error("Legacy managers not available in this implementation");
+    }
+  }
+
+  /**
+   * Check if a manager is using the new composed approach
+   */
+  static isComposed(manager: unknown): boolean {
+    return (
+      manager instanceof ComposedAuthenticationManager ||
+      manager instanceof ComposedRequestManager ||
+      manager instanceof RequestManagerAdapter
+    );
+  }
+
+  /**
+   * Get migration progress information
+   */
+  static getMigrationStatus(managers: unknown[]): {
+    total: number;
+    composed: number;
+    inheritance: number;
+    percentage: number;
+  } {
+    const total = managers.length;
+    const composed = managers.filter((manager) => MigrationAdapter.isComposed(manager)).length;
+    const inheritance = total - composed;
+    const percentage = total > 0 ? Math.round((composed / total) * 100) : 0;
+
+    return {
+      total,
+      composed,
+      inheritance,
+      percentage,
+    };
+  }
+
+  /**
+   * Performance comparison between inheritance and composition approaches
+   */
+  static async performanceComparison(
+    config: WordPressClientConfig,
+    iterations: number = 100,
+  ): Promise<{
+    inheritance: number;
+    composition: number;
+    improvement: string;
+  }> {
+    // Running performance comparison with iterations
+
+    // Test composition approach only (inheritance baseline would require old managers)
+    const compositionStart = performance.now();
+    for (let i = 0; i < iterations; i++) {
+      const authManager = ComposedAuthenticationManager.create(config);
+      const requestManager = ComposedRequestManager.create(config, authManager);
+      // Simulate usage
+      authManager.isAuthenticated();
+      requestManager.getStats();
+    }
+    const compositionTime = performance.now() - compositionStart;
+
+    return {
+      inheritance: 0, // Would require old managers to measure
+      composition: compositionTime,
+      improvement: "Composition pattern implemented",
+    };
+  }
+
+  /**
+   * Migration guide generator
+   */
+  static generateMigrationGuide(): string {
+    return `
+# Migration Guide: Inheritance to Composition
+
+## Overview
+This migration guide helps transition from inheritance-based managers to composition-based managers.
+
+## Benefits of Composition
+1. **Better Testability**: Each component can be tested in isolation
+2. **Improved Flexibility**: Components can be mixed and matched
+3. **SOLID Principles**: Better adherence to Single Responsibility and Dependency Inversion
+4. **Reduced Coupling**: Components depend on interfaces, not concrete classes
+
+## Migration Steps
+
+### Step 1: Update Imports
+\`\`\`typescript
+// Old approach
+import { RequestManager } from '@/client/managers/RequestManager.js';
+import { AuthenticationManager } from '@/client/managers/AuthenticationManager.js';
+
+// New approach
+import { createComposedWordPressClient } from '@/client/managers/composed';
+\`\`\`
+
+### Step 2: Replace Manager Creation
+\`\`\`typescript
+// Old approach
+const authManager = new AuthenticationManager(config);
+const requestManager = new RequestManager(config, authManager);
+
+// New approach
+const client = await createComposedWordPressClient(config);
+\`\`\`
+
+### Step 3: Update Usage Patterns
+\`\`\`typescript
+// Old approach
+await requestManager.request('GET', '/wp/v2/posts');
+
+// New approach
+await client.request('GET', '/wp/v2/posts');
+// or use convenience methods
+await client.getPosts();
+\`\`\`
+
+### Step 4: Handle Dependency Injection
+\`\`\`typescript
+// Custom implementations can be injected
+const customErrorHandler = new CustomErrorHandler();
+const factory = new ComposedManagerFactory();
+const client = await factory.createComposedClient({
+  clientConfig: config,
+  customErrorHandler
+});
+\`\`\`
+
+## Gradual Migration
+Use the MigrationAdapter for gradual migration:
+
+\`\`\`typescript
+import { MigrationAdapter } from '@/client/managers/composed';
+
+// Feature flag to control migration
+const USE_COMPOSITION = process.env.USE_COMPOSED_MANAGERS === 'true';
+
+const { requestManager, authManager } = await MigrationAdapter.createManagers(
+  config, 
+  USE_COMPOSITION
+);
+\`\`\`
+
+## Testing the Migration
+1. Run existing tests with both approaches
+2. Performance test both implementations
+3. Gradually migrate components one by one
+4. Monitor for any behavioral differences
+
+## Rollback Plan
+The MigrationAdapter provides backward compatibility, allowing easy rollback if issues arise.
+`;
+  }
+}

package/src/client/managers/composed/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Composed Managers Export
+ * 
+ * This module provides composition-based alternatives to the inheritance-based managers.
+ * The composed managers offer better testability, flexibility, and adherence to SOLID principles.
+ * 
+ * Usage:
+ * ```typescript
+ * import { createComposedWordPressClient } from '@/client/managers/composed';
+ * 
+ * const client = await createComposedWordPressClient(config);
+ * const posts = await client.getPosts();
+ * ```
+ */
+
+// Interfaces
+export type {
+  ConfigurationProvider,
+  ErrorHandler,
+  ParameterValidator,
+  AuthenticationProvider,
+  RequestHandler,
+  BaseManagerContract,
+  ComposedManager,
+  ManagerFactory,
+  ManagerCompositionConfig
+} from "../interfaces/ManagerInterfaces.js";
+
+// Implementations
+export { ConfigurationProviderImpl } from "../implementations/ConfigurationProviderImpl.js";
+export { ErrorHandlerImpl } from "../implementations/ErrorHandlerImpl.js";
+export { ParameterValidatorImpl } from "../implementations/ParameterValidatorImpl.js";
+
+// Composed Managers
+export { ComposedAuthenticationManager } from "../ComposedAuthenticationManager.js";
+export { ComposedRequestManager } from "../ComposedRequestManager.js";
+
+// Factory and Client
+export { 
+  ComposedManagerFactory,
+  ComposedWordPressClient,
+  createComposedWordPressClient,
+  type ComposedWordPressClientDependencies
+} from "../ComposedManagerFactory.js";
+
+// Migration utilities (for gradual migration from inheritance to composition)
+export { MigrationAdapter } from "./MigrationAdapter.js";

package/src/client/managers/implementations/ConfigurationProviderImpl.ts

@@ -0,0 +1,52 @@
+/**
+ * Configuration Provider Implementation
+ * Provides centralized configuration management for managers
+ */
+
+import type { WordPressClientConfig } from "@/types/client.js";
+import type { ConfigurationProvider } from "../interfaces/ManagerInterfaces.js";
+
+export class ConfigurationProviderImpl implements ConfigurationProvider {
+  public readonly config: WordPressClientConfig;
+
+  constructor(config: WordPressClientConfig) {
+    // Create defensive copy to prevent external mutation
+    this.config = Object.freeze({ ...config });
+  }
+
+  /**
+   * Get configuration value by path (dot notation)
+   */
+  getConfigValue<T = unknown>(path: string, defaultValue?: T): T | undefined {
+    return (
+      (path.split(".").reduce((obj, key) => (obj as Record<string, unknown>)?.[key], this.config as unknown) as T) ??
+      defaultValue
+    );
+  }
+
+  /**
+   * Validate configuration completeness
+   */
+  validateConfiguration(): void {
+    const required = ["baseUrl", "auth"];
+    const missing = required.filter((field) => !this.config[field as keyof WordPressClientConfig]);
+
+    if (missing.length > 0) {
+      throw new Error(`Missing required configuration: ${missing.join(", ")}`);
+    }
+  }
+
+  /**
+   * Get timeout value with fallbacks
+   */
+  getTimeout(): number {
+    return this.config.timeout || 30000;
+  }
+
+  /**
+   * Check if debug mode is enabled
+   */
+  isDebugEnabled(): boolean {
+    return Boolean((this.config as unknown as Record<string, unknown>).debug);
+  }
+}

package/src/client/managers/implementations/ErrorHandlerImpl.ts

@@ -0,0 +1,102 @@
+/**
+ * Error Handler Implementation
+ * Provides standardized error handling and logging for managers
+ */
+
+import { WordPressAPIError } from "@/types/client.js";
+import { debug, logError } from "@/utils/debug.js";
+import { getErrorMessage } from "@/utils/error.js";
+import type { ErrorHandler, ConfigurationProvider } from "../interfaces/ManagerInterfaces.js";
+
+export class ErrorHandlerImpl implements ErrorHandler {
+  constructor(private configProvider: ConfigurationProvider) {}
+
+  /**
+   * Handle and transform errors with context
+   */
+  handleError(error: unknown, operation: string): never {
+    logError(`${operation} failed:`, error as Record<string, unknown>);
+
+    if (error instanceof WordPressAPIError) {
+      throw error;
+    }
+
+    // Type guard for error-like objects
+    const isErrorLike = (err: unknown): err is { name?: string; code?: string; message?: string } => {
+      return typeof err === "object" && err !== null;
+    };
+
+    if (isErrorLike(error)) {
+      if (error.name === "AbortError" || error.code === "ABORT_ERR") {
+        throw new WordPressAPIError(
+          `Request timeout after ${this.configProvider.config.timeout}ms`, 
+          408, 
+          "timeout"
+        );
+      }
+
+      if (error.code === "ECONNREFUSED" || error.code === "ENOTFOUND") {
+        throw new WordPressAPIError(
+          `Cannot connect to WordPress site: ${this.configProvider.config.baseUrl}`, 
+          503, 
+          "connection_failed"
+        );
+      }
+    }
+
+    const message = getErrorMessage(error);
+    throw new WordPressAPIError(`${operation} failed: ${message}`, 500, "unknown_error");
+  }
+
+  /**
+   * Log successful operations
+   */
+  logSuccess(operation: string, details?: unknown): void {
+    debug.log(`${operation} completed successfully`, details);
+  }
+
+  /**
+   * Handle authentication errors specifically
+   */
+  handleAuthError(error: unknown, operation: string): never {
+    logError(`Authentication failed during ${operation}:`, error as Record<string, unknown>);
+    
+    if (error instanceof WordPressAPIError) {
+      throw error;
+    }
+
+    const message = getErrorMessage(error);
+    throw new WordPressAPIError(
+      `Authentication failed during ${operation}: ${message}`, 
+      401, 
+      "auth_failed"
+    );
+  }
+
+  /**
+   * Handle rate limit errors specifically
+   */
+  handleRateLimitError(retryAfter?: number): never {
+    const message = retryAfter 
+      ? `Rate limit exceeded. Retry after ${retryAfter} seconds.`
+      : "Rate limit exceeded.";
+    
+    throw new WordPressAPIError(message, 429, "rate_limited");
+  }
+
+  /**
+   * Create context-aware error
+   */
+  createContextualError(baseError: unknown, context: Record<string, unknown>): WordPressAPIError {
+    const message = getErrorMessage(baseError);
+    const contextString = Object.entries(context)
+      .map(([key, value]) => `${key}=${String(value)}`)
+      .join(', ');
+    
+    return new WordPressAPIError(
+      `${message} (Context: ${contextString})`,
+      500,
+      "contextual_error"
+    );
+  }
+}

package/src/client/managers/implementations/ParameterValidatorImpl.ts

@@ -0,0 +1,221 @@
+/**
+ * Parameter Validator Implementation
+ * Provides comprehensive parameter validation for managers
+ */
+
+import { WordPressAPIError } from "@/types/client.js";
+import type { ParameterValidator } from "../interfaces/ManagerInterfaces.js";
+
+export class ParameterValidatorImpl implements ParameterValidator {
+  /**
+   * Validate required parameters are present
+   */
+  validateRequired(params: Record<string, unknown>, requiredFields: string[]): void {
+    for (const field of requiredFields) {
+      if (params[field] === undefined || params[field] === null) {
+        throw new WordPressAPIError(`Missing required parameter: ${field}`, 400, "missing_parameter");
+      }
+    }
+  }
+
+  /**
+   * Validate parameter types and formats
+   */
+  validateParameters<T>(params: unknown, schema?: unknown): T {
+    if (params === null || params === undefined) {
+      throw new WordPressAPIError("Parameters cannot be null or undefined", 400, "invalid_parameters");
+    }
+
+    // If no schema provided, return params as-is with type assertion
+    if (!schema) {
+      return params as T;
+    }
+
+    // Basic runtime validation (can be extended with schema validation libraries)
+    if (typeof params !== "object") {
+      throw new WordPressAPIError("Parameters must be an object", 400, "invalid_parameters");
+    }
+
+    return params as T;
+  }
+
+  /**
+   * Validate string parameters
+   */
+  validateString(value: unknown, fieldName: string, options?: {
+    required?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+  }): string {
+    if (options?.required && (value === undefined || value === null || value === "")) {
+      throw new WordPressAPIError(`${fieldName} is required`, 400, "missing_parameter");
+    }
+
+    if (value === undefined || value === null) {
+      return "";
+    }
+
+    if (typeof value !== "string") {
+      throw new WordPressAPIError(`${fieldName} must be a string`, 400, "invalid_parameter_type");
+    }
+
+    if (options?.minLength && value.length < options.minLength) {
+      throw new WordPressAPIError(
+        `${fieldName} must be at least ${options.minLength} characters`, 
+        400, 
+        "parameter_too_short"
+      );
+    }
+
+    if (options?.maxLength && value.length > options.maxLength) {
+      throw new WordPressAPIError(
+        `${fieldName} must be no more than ${options.maxLength} characters`, 
+        400, 
+        "parameter_too_long"
+      );
+    }
+
+    if (options?.pattern && !options.pattern.test(value)) {
+      throw new WordPressAPIError(
+        `${fieldName} format is invalid`, 
+        400, 
+        "invalid_parameter_format"
+      );
+    }
+
+    return value;
+  }
+
+  /**
+   * Validate numeric parameters
+   */
+  validateNumber(value: unknown, fieldName: string, options?: {
+    required?: boolean;
+    min?: number;
+    max?: number;
+    integer?: boolean;
+  }): number {
+    if (options?.required && (value === undefined || value === null)) {
+      throw new WordPressAPIError(`${fieldName} is required`, 400, "missing_parameter");
+    }
+
+    if (value === undefined || value === null) {
+      return 0;
+    }
+
+    const numValue = typeof value === "string" ? parseFloat(value) : Number(value);
+
+    if (isNaN(numValue)) {
+      throw new WordPressAPIError(`${fieldName} must be a valid number`, 400, "invalid_parameter_type");
+    }
+
+    if (options?.integer && !Number.isInteger(numValue)) {
+      throw new WordPressAPIError(`${fieldName} must be an integer`, 400, "invalid_parameter_type");
+    }
+
+    if (options?.min !== undefined && numValue < options.min) {
+      throw new WordPressAPIError(
+        `${fieldName} must be at least ${options.min}`, 
+        400, 
+        "parameter_too_small"
+      );
+    }
+
+    if (options?.max !== undefined && numValue > options.max) {
+      throw new WordPressAPIError(
+        `${fieldName} must be no more than ${options.max}`, 
+        400, 
+        "parameter_too_large"
+      );
+    }
+
+    return numValue;
+  }
+
+  /**
+   * Validate array parameters
+   */
+  validateArray<T>(value: unknown, fieldName: string, options?: {
+    required?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    itemValidator?: (item: unknown) => T;
+  }): T[] {
+    if (options?.required && (value === undefined || value === null)) {
+      throw new WordPressAPIError(`${fieldName} is required`, 400, "missing_parameter");
+    }
+
+    if (value === undefined || value === null) {
+      return [];
+    }
+
+    if (!Array.isArray(value)) {
+      throw new WordPressAPIError(`${fieldName} must be an array`, 400, "invalid_parameter_type");
+    }
+
+    if (options?.minLength && value.length < options.minLength) {
+      throw new WordPressAPIError(
+        `${fieldName} must contain at least ${options.minLength} items`, 
+        400, 
+        "array_too_short"
+      );
+    }
+
+    if (options?.maxLength && value.length > options.maxLength) {
+      throw new WordPressAPIError(
+        `${fieldName} must contain no more than ${options.maxLength} items`, 
+        400, 
+        "array_too_long"
+      );
+    }
+
+    if (options?.itemValidator) {
+      try {
+        return value.map((item, index) => {
+          try {
+            return options.itemValidator!(item);
+          } catch (error) {
+            throw new WordPressAPIError(
+              `${fieldName}[${index}] validation failed: ${getErrorMessage(error)}`,
+              400,
+              "array_item_invalid"
+            );
+          }
+        });
+      } catch (error) {
+        if (error instanceof WordPressAPIError) {
+          throw error;
+        }
+        throw new WordPressAPIError(
+          `${fieldName} validation failed: ${getErrorMessage(error)}`,
+          400,
+          "array_validation_failed"
+        );
+      }
+    }
+
+    return value as T[];
+  }
+
+  /**
+   * Validate WordPress ID parameters
+   */
+  validateWordPressId(value: unknown, fieldName: string = "id"): number {
+    const id = this.validateNumber(value, fieldName, {
+      required: true,
+      min: 1,
+      integer: true
+    });
+
+    return id;
+  }
+}
+
+// Helper function to get error message
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}