sfcc-dev-mcp 1.0.15 → 1.0.19

package/src/utils/job-log-utils.ts

@@ -1,78 +0,0 @@
-/**
- * Shared utilities for job log operations
- */
-
-export class JobLogValidators {
-  /**
-   * Allowed log levels for job logs (includes 'all' for job-specific operations)
-   */
-  static readonly ALLOWED_LEVELS = ['error', 'warn', 'info', 'debug', 'all'] as const;
-
-  /**
-   * Validate job log level parameter
-   * @param level - The level to validate
-   * @param toolName - Optional tool name for better error messages
-   */
-  static validateJobLogLevel(level: string, toolName?: string): void {
-    if (!this.ALLOWED_LEVELS.includes(level as any)) {
-      const errorPrefix = toolName ? `${toolName}: ` : '';
-      throw new Error(
-        `${errorPrefix}Invalid log level: ${level}. Must be one of: ${this.ALLOWED_LEVELS.join(', ')}`,
-      );
-    }
-  }
-
-  /**
-   * Get default limit based on operation type
-   * @param operationType - Type of operation ('search' | 'entries' | 'files')
-   */
-  static getDefaultLimit(operationType: 'search' | 'entries' | 'files'): number {
-    switch (operationType) {
-      case 'search':
-        return 20;
-      case 'entries':
-        return 10;
-      case 'files':
-        return 10;
-      default:
-        return 10;
-    }
-  }
-}
-
-export class JobLogFormatters {
-  /**
-   * Format a consistent log message for job operations
-   * @param operation - The operation being performed
-   * @param params - Parameters for the operation
-   */
-  static formatJobLogMessage(
-    operation: string,
-    params: {
-      jobName?: string;
-      level?: string;
-      limit?: number;
-      pattern?: string;
-    },
-  ): string {
-    const parts = [operation];
-
-    if (params.jobName) {
-      parts.push(`jobName=${params.jobName}`);
-    }
-
-    if (params.level) {
-      parts.push(`level=${params.level}`);
-    }
-
-    if (params.limit !== undefined) {
-      parts.push(`limit=${params.limit}`);
-    }
-
-    if (params.pattern) {
-      parts.push(`pattern="${params.pattern}"`);
-    }
-
-    return parts.join(' ');
-  }
-}

package/src/utils/log-cache.ts

@@ -1,134 +0,0 @@
-import { SFCCLogClient } from '../clients/log-client.js';
-
-/**
- * Simple in-memory cache for log operations
- * Provides short-term caching to avoid repeated API calls for common operations
- */
-export class LogCache {
-  private cache = new Map<string, { data: any; timestamp: number; ttl: number }>();
-  private readonly DEFAULT_TTL = 5000; // 5 seconds default TTL
-  private readonly MAX_CACHE_SIZE = 100; // Prevent memory bloat
-
-  /**
-   * Get cached data if available and not expired
-   */
-  get<T>(key: string): T | null {
-    const entry = this.cache.get(key);
-    if (!entry) {
-      return null;
-    }
-
-    // Check if expired
-    if (Date.now() - entry.timestamp > entry.ttl) {
-      this.cache.delete(key);
-      return null;
-    }
-
-    return entry.data as T;
-  }
-
-  /**
-   * Set cached data with TTL
-   */
-  set(key: string, data: any, ttl: number = this.DEFAULT_TTL): void {
-    // Implement basic LRU by removing oldest entries when cache is full
-    if (this.cache.size >= this.MAX_CACHE_SIZE) {
-      const oldestKey = this.cache.keys().next().value;
-      if (oldestKey) {
-        this.cache.delete(oldestKey);
-      }
-    }
-
-    this.cache.set(key, {
-      data,
-      timestamp: Date.now(),
-      ttl,
-    });
-  }
-
-  /**
-   * Generate cache key for log operations
-   */
-  static generateKey(operation: string, args: Record<string, any>): string {
-    const sortedArgs = Object.keys(args)
-      .sort()
-      .map(key => `${key}=${args[key]}`)
-      .join('&');
-
-    return `${operation}:${sortedArgs}`;
-  }
-
-  /**
-   * Clear all cached entries
-   */
-  clear(): void {
-    this.cache.clear();
-  }
-
-  /**
-   * Remove expired entries (can be called periodically)
-   */
-  cleanup(): void {
-    const now = Date.now();
-    for (const [key, entry] of this.cache.entries()) {
-      if (now - entry.timestamp > entry.ttl) {
-        this.cache.delete(key);
-      }
-    }
-  }
-}
-
-/**
- * Enhanced log client wrapper with caching capabilities
- * Provides transparent caching for frequently accessed log operations
- */
-export class CachedLogClient {
-  private cache = new LogCache();
-  private readonly CACHEABLE_OPERATIONS = new Set([
-    'list_log_files',
-    'get_latest_job_log_files',
-    'summarize_logs',
-  ]);
-
-  constructor(private logClient: SFCCLogClient) {}
-
-  /**
-   * Execute operation with caching if applicable
-   */
-  async executeWithCache<T>(
-    operation: string,
-    args: Record<string, any>,
-    executor: () => Promise<T>,
-    ttl?: number,
-  ): Promise<T> {
-    // Only cache certain operations to avoid stale data issues
-    if (!this.CACHEABLE_OPERATIONS.has(operation)) {
-      return executor();
-    }
-
-    const cacheKey = LogCache.generateKey(operation, args);
-    const cached = this.cache.get<T>(cacheKey);
-
-    if (cached !== null) {
-      return cached;
-    }
-
-    const result = await executor();
-    this.cache.set(cacheKey, result, ttl);
-    return result;
-  }
-
-  /**
-   * Clear cache - useful when log state might have changed
-   */
-  clearCache(): void {
-    this.cache.clear();
-  }
-
-  /**
-   * Cleanup expired cache entries
-   */
-  cleanupCache(): void {
-    this.cache.cleanup();
-  }
-}

package/src/utils/log-tool-config.ts

@@ -1,98 +0,0 @@
-import { ToolSpec, LogToolValidators, LogMessageFormatter } from './log-tool-utils.js';
-import { ValidationHelpers, CommonValidations } from '../core/handlers/validation-helpers.js';
-import { LogToolName, getLimit } from './log-tool-constants.js';
-
-/**
- * Configuration for standard log tools
- * Maps each tool to its validation, execution, and messaging logic
- */
-export const LOG_TOOL_CONFIG: Record<LogToolName, ToolSpec> = {
-  get_latest_error: {
-    defaults: (args) => ({
-      limit: getLimit(args.limit as number, 'latest'),
-    }),
-    validate: (args) => LogToolValidators.validateLimit(args.limit as number, 'get_latest_error'),
-    exec: async (args, client) => client.getLatestLogs('error', args.limit as number, args.date as string),
-    logMessage: (args) => LogMessageFormatter.formatLatestLogs('error', args.limit as number, args.date as string),
-  },
-
-  get_latest_warn: {
-    defaults: (args) => ({
-      limit: getLimit(args.limit as number, 'latest'),
-    }),
-    validate: (args) => LogToolValidators.validateLimit(args.limit as number, 'get_latest_warn'),
-    exec: async (args, client) => client.getLatestLogs('warn', args.limit as number, args.date as string),
-    logMessage: (args) => LogMessageFormatter.formatLatestLogs('warn', args.limit as number, args.date as string),
-  },
-
-  get_latest_info: {
-    defaults: (args) => ({
-      limit: getLimit(args.limit as number, 'latest'),
-    }),
-    validate: (args) => LogToolValidators.validateLimit(args.limit as number, 'get_latest_info'),
-    exec: async (args, client) => client.getLatestLogs('info', args.limit as number, args.date as string),
-    logMessage: (args) => LogMessageFormatter.formatLatestLogs('info', args.limit as number, args.date as string),
-  },
-
-  get_latest_debug: {
-    defaults: (args) => ({
-      limit: getLimit(args.limit as number, 'latest'),
-    }),
-    validate: (args) => LogToolValidators.validateLimit(args.limit as number, 'get_latest_debug'),
-    exec: async (args, client) => client.getLatestLogs('debug', args.limit as number, args.date as string),
-    logMessage: (args) => LogMessageFormatter.formatLatestLogs('debug', args.limit as number, args.date as string),
-  },
-
-  summarize_logs: {
-    exec: async (args, client) => client.summarizeLogs(args.date as string),
-    logMessage: (args) => LogMessageFormatter.formatSummarizeLogs(args.date as string),
-  },
-
-  search_logs: {
-    defaults: (args) => ({
-      limit: getLimit(args.limit as number, 'search'),
-    }),
-    validate: (args, toolName) => {
-      ValidationHelpers.validateArguments(args, CommonValidations.requiredString('pattern'), toolName);
-      LogToolValidators.validateLimit(args.limit as number, toolName);
-      if (args.logLevel) {
-        LogToolValidators.validateLogLevel(args.logLevel as string, toolName);
-      }
-    },
-    exec: async (args, client) => client.searchLogs(
-      args.pattern as string,
-      args.logLevel as any,
-      args.limit as number,
-      args.date as string,
-    ),
-    logMessage: (args) => LogMessageFormatter.formatSearchLogs(
-      args.pattern as string,
-      args.logLevel as string,
-      args.limit as number,
-      args.date as string,
-    ),
-  },
-
-  list_log_files: {
-    exec: async (args, client) => client.listLogFiles(),
-    logMessage: () => LogMessageFormatter.formatListLogFiles(),
-  },
-
-  get_log_file_contents: {
-    validate: (args, toolName) => {
-      ValidationHelpers.validateArguments(args, CommonValidations.requiredString('filename'), toolName);
-      LogToolValidators.validateFilename(args.filename as string, toolName);
-      LogToolValidators.validateMaxBytes(args.maxBytes as number, toolName);
-    },
-    exec: async (args, client) => client.getLogFileContents(
-      args.filename as string,
-      args.maxBytes as number,
-      args.tailOnly as boolean,
-    ),
-    logMessage: (args) => LogMessageFormatter.formatGetLogFileContents(
-      args.filename as string,
-      args.maxBytes as number,
-      args.tailOnly as boolean,
-    ),
-  },
-};

package/src/utils/log-tool-utils.ts

@@ -1,122 +0,0 @@
-import { ToolArguments } from '../core/handlers/base-handler.js';
-import { SFCCLogClient } from '../clients/log-client.js';
-import { LogLevel, isValidLogLevel } from './log-tool-constants.js';
-
-/**
- * Configuration interface for tool dispatch
- */
-export interface ToolSpec<T = any> {
-  validate?: (args: ToolArguments, toolName: string) => void;
-  defaults?: (args: ToolArguments) => Record<string, any>;
-  exec: (args: ToolArguments, client: SFCCLogClient) => Promise<T>;
-  logMessage: (args: ToolArguments) => string;
-}
-
-/**
- * Validation utilities for log tools
- */
-export class LogToolValidators {
-  static validateLogLevel(level: string, toolName: string): void {
-    if (!isValidLogLevel(level)) {
-      throw new Error(`Invalid log level '${level}' for ${toolName}. Valid levels: ${Object.values(LogLevel).join(', ')}`);
-    }
-  }
-
-  static validateLimit(limit: number | undefined, toolName: string): void {
-    if (limit !== undefined) {
-      // Validate type first
-      if (typeof limit !== 'number' || isNaN(limit)) {
-        throw new Error(`Invalid limit '${limit}' for ${toolName}. Must be a valid number`);
-      }
-      // Then validate range
-      if (limit <= 0 || limit > 1000) {
-        throw new Error(`Invalid limit '${limit}' for ${toolName}. Must be between 1 and 1000`);
-      }
-    }
-  }
-
-  static validateMaxBytes(maxBytes: number | undefined, toolName: string): void {
-    if (maxBytes !== undefined) {
-      // Validate type first
-      if (typeof maxBytes !== 'number' || isNaN(maxBytes)) {
-        throw new Error(`Invalid maxBytes '${maxBytes}' for ${toolName}. Must be a valid number`);
-      }
-      // Then validate range
-      if (maxBytes <= 0 || maxBytes > 10_000_000) { // 10MB limit
-        throw new Error(`Invalid maxBytes '${maxBytes}' for ${toolName}. Must be between 1 and 10,000,000`);
-      }
-    }
-  }
-
-  static validateFilename(filename: string, toolName: string): void {
-    if (!filename || filename.trim().length === 0) {
-      throw new Error(`Filename is required for ${toolName}`);
-    }
-
-    // Prevent path traversal
-    if (filename.includes('..') || filename.includes('\\')) {
-      throw new Error(`Invalid filename '${filename}' for ${toolName}. Path traversal not allowed`);
-    }
-  }
-}
-
-/**
- * Message formatting utilities for log tools
- */
-export class LogMessageFormatter {
-  static formatLatestLogs(level: string, limit: number, date?: string): string {
-    return `Fetching latest ${level} logs limit=${limit} date=${date ?? 'today'}`;
-  }
-
-  static formatSummarizeLogs(date?: string): string {
-    return `Summarizing logs for date ${date ?? 'today'}`;
-  }
-
-  static formatSearchLogs(pattern: string, logLevel?: string, limit?: number, _date?: string): string {
-    // For backward compatibility with existing tests, don't include date in message
-    return `Searching logs pattern="${pattern}" level=${logLevel ?? 'all'} limit=${limit ?? 20}`;
-  }
-
-  static formatListLogFiles(): string {
-    return 'Listing log files';
-  }
-
-  static formatGetLogFileContents(filename: string, maxBytes?: number, tailOnly?: boolean): string {
-    return `Reading log file contents: ${filename} (maxBytes=${maxBytes ?? 'default'}, tailOnly=${tailOnly ?? false})`;
-  }
-
-  static formatJobLogMessage(operation: string, params: Record<string, any>): string {
-    const paramStr = Object.entries(params)
-      .filter(([_, value]) => value !== undefined)
-      .map(([key, value]) => `${key}=${value}`)
-      .join(' ');
-
-    return paramStr ? `${operation} ${paramStr}` : operation;
-  }
-}
-
-/**
- * Utility functions for argument processing
- */
-export class LogToolUtils {
-  static applyDefaults(spec: ToolSpec, args: ToolArguments): ToolArguments {
-    if (!spec.defaults) {
-      return args;
-    }
-
-    const defaults = spec.defaults(args);
-    return { ...args, ...defaults };
-  }
-
-  static createValidatedArgs(spec: ToolSpec, args: ToolArguments, toolName: string): ToolArguments {
-    // Apply defaults first
-    const processedArgs = LogToolUtils.applyDefaults(spec, args);
-
-    // Validate if validator exists
-    if (spec.validate) {
-      spec.validate(processedArgs, toolName);
-    }
-
-    return processedArgs;
-  }
-}

package/tests/best-practices-handler.test.ts

@@ -1,236 +0,0 @@
-import { BestPracticesToolHandler } from '../src/core/handlers/best-practices-handler.js';
-import { HandlerContext } from '../src/core/handlers/base-handler.js';
-import { Logger } from '../src/utils/logger.js';
-
-// Mock the SFCCBestPracticesClient
-const mockBestPracticesClient = {
-  getAvailableGuides: jest.fn(),
-  getBestPracticeGuide: jest.fn(),
-  searchBestPractices: jest.fn(),
-  getHookReference: jest.fn(),
-};
-
-jest.mock('../src/clients/best-practices-client.js', () => ({
-  SFCCBestPracticesClient: jest.fn(() => mockBestPracticesClient),
-}));
-
-describe('BestPracticesToolHandler', () => {
-  let mockLogger: jest.Mocked<Logger>;
-  let mockClient: typeof mockBestPracticesClient;
-  let context: HandlerContext;
-  let handler: BestPracticesToolHandler;
-
-  beforeEach(() => {
-    mockLogger = {
-      debug: jest.fn(),
-      log: jest.fn(),
-      error: jest.fn(),
-      timing: jest.fn(),
-      methodEntry: jest.fn(),
-      methodExit: jest.fn(),
-    } as any;
-
-    // Reset mocks
-    jest.clearAllMocks();
-
-    // Use the mock client directly
-    mockClient = mockBestPracticesClient;
-
-    jest.spyOn(Logger, 'getChildLogger').mockReturnValue(mockLogger);
-
-    context = {
-      logger: mockLogger,
-      config: null as any,
-      capabilities: { canAccessLogs: false, canAccessOCAPI: false },
-    };
-
-    handler = new BestPracticesToolHandler(context, 'BestPractices');
-  });
-
-  afterEach(() => {
-    jest.restoreAllMocks();
-  });
-
-  // Helper function to initialize handler for tests that need it
-  const initializeHandler = async () => {
-    await (handler as any).initialize();
-  };
-
-  describe('canHandle', () => {
-    it('should handle best practices tools', () => {
-      expect(handler.canHandle('get_available_best_practice_guides')).toBe(true);
-      expect(handler.canHandle('get_best_practice_guide')).toBe(true);
-      expect(handler.canHandle('search_best_practices')).toBe(true);
-      expect(handler.canHandle('get_hook_reference')).toBe(true);
-    });
-
-    it('should not handle non-best-practices tools', () => {
-      expect(handler.canHandle('get_latest_error')).toBe(false);
-      expect(handler.canHandle('unknown_tool')).toBe(false);
-    });
-  });
-
-  describe('initialization', () => {
-    it('should initialize best practices client', async () => {
-      await initializeHandler();
-
-      const MockedConstructor = jest.requireMock('../src/clients/best-practices-client.js').SFCCBestPracticesClient;
-      expect(MockedConstructor).toHaveBeenCalled();
-      expect(mockLogger.debug).toHaveBeenCalledWith('Best practices client initialized');
-    });
-  });
-
-  describe('disposal', () => {
-    it('should dispose best practices client properly', async () => {
-      await initializeHandler();
-      await (handler as any).dispose();
-
-      expect(mockLogger.debug).toHaveBeenCalledWith('Best practices client disposed');
-    });
-  });
-
-  describe('get_available_best_practice_guides tool', () => {
-    beforeEach(async () => {
-      await initializeHandler();
-      mockClient.getAvailableGuides.mockResolvedValue([
-        { name: 'cartridge_creation', title: 'Cartridge Creation', description: 'Best practices for cartridge creation' },
-        { name: 'isml_templates', title: 'ISML Templates', description: 'Best practices for ISML templates' },
-      ]);
-    });
-
-    it('should handle get_available_best_practice_guides', async () => {
-      const result = await handler.handle('get_available_best_practice_guides', {}, Date.now());
-
-      expect(mockClient.getAvailableGuides).toHaveBeenCalled();
-      expect(result.content[0].text).toContain('cartridge_creation');
-      expect(result.content[0].text).toContain('isml_templates');
-    });
-  });
-
-  describe('get_best_practice_guide tool', () => {
-    beforeEach(async () => {
-      await initializeHandler();
-      mockClient.getBestPracticeGuide.mockResolvedValue({
-        title: 'Cartridge Creation Best Practices',
-        description: 'Complete guide for creating custom cartridges',
-        sections: ['Overview', 'Setup', 'Configuration'],
-        content: 'Detailed content about cartridge creation...',
-      });
-    });
-
-    it('should handle get_best_practice_guide with guideName', async () => {
-      const args = { guideName: 'cartridge_creation' };
-      const result = await handler.handle('get_best_practice_guide', args, Date.now());
-
-      expect(mockClient.getBestPracticeGuide).toHaveBeenCalledWith('cartridge_creation');
-      expect(result.content[0].text).toContain('Cartridge Creation Best Practices');
-    });
-
-    it('should throw error when guideName is missing', async () => {
-      const result = await handler.handle('get_best_practice_guide', {}, Date.now());
-      expect(result.isError).toBe(true);
-      expect(result.content[0].text).toContain('guideName must be a non-empty string');
-    });
-  });
-
-  describe('search_best_practices tool', () => {
-    beforeEach(async () => {
-      await initializeHandler();
-      mockClient.searchBestPractices.mockResolvedValue([
-        { guide: 'cartridge_creation', section: 'Setup', content: 'Cartridge setup instructions...' },
-        { guide: 'security', section: 'Authentication', content: 'Security best practices...' },
-      ]);
-    });
-
-    it('should handle search_best_practices with query', async () => {
-      const args = { query: 'validation' };
-      const result = await handler.handle('search_best_practices', args, Date.now());
-
-      expect(mockClient.searchBestPractices).toHaveBeenCalledWith('validation');
-      expect(result.content[0].text).toContain('cartridge_creation');
-      expect(result.content[0].text).toContain('security');
-    });
-
-    it('should throw error when query is missing', async () => {
-      const result = await handler.handle('search_best_practices', {}, Date.now());
-      expect(result.isError).toBe(true);
-      expect(result.content[0].text).toContain('query must be a non-empty string');
-    });
-
-    it('should throw error when query is empty', async () => {
-      const result = await handler.handle('search_best_practices', { query: '' }, Date.now());
-      expect(result.isError).toBe(true);
-      expect(result.content[0].text).toContain('query must be a non-empty string');
-    });
-  });
-
-  describe('get_hook_reference tool', () => {
-    beforeEach(async () => {
-      await initializeHandler();
-      mockClient.getHookReference.mockResolvedValue({
-        type: 'OCAPI Hooks',
-        hooks: [
-          { endpoint: 'customers.post', description: 'Customer creation hook' },
-          { endpoint: 'orders.get', description: 'Order retrieval hook' },
-        ],
-      });
-    });
-
-    it('should handle get_hook_reference with guideName', async () => {
-      const args = { guideName: 'ocapi_hooks' };
-      const result = await handler.handle('get_hook_reference', args, Date.now());
-
-      expect(mockClient.getHookReference).toHaveBeenCalledWith('ocapi_hooks');
-      expect(result.content[0].text).toContain('OCAPI Hooks');
-      expect(result.content[0].text).toContain('customers.post');
-    });
-
-    it('should throw error when guideName is missing', async () => {
-      const result = await handler.handle('get_hook_reference', {}, Date.now());
-      expect(result.isError).toBe(true);
-      expect(result.content[0].text).toContain('guideName must be a non-empty string');
-    });
-  });
-
-  describe('error handling', () => {
-    beforeEach(async () => {
-      await initializeHandler();
-    });
-
-    it('should handle client errors gracefully', async () => {
-      mockClient.getBestPracticeGuide.mockRejectedValue(new Error('Guide not found'));
-
-      const result = await handler.handle('get_best_practice_guide', { guideName: 'unknown_guide' }, Date.now());
-      expect(result.isError).toBe(true);
-      expect(result.content[0].text).toContain('Guide not found');
-    });
-
-    it('should throw error for unsupported tools', async () => {
-      await expect(handler.handle('unsupported_tool', {}, Date.now()))
-        .rejects.toThrow('Unsupported tool');
-    });
-  });
-
-  describe('timing and logging', () => {
-    beforeEach(async () => {
-      await initializeHandler();
-      mockClient.getAvailableGuides.mockResolvedValue([]);
-    });
-
-    it('should log timing information', async () => {
-      const startTime = Date.now();
-      await handler.handle('get_available_best_practice_guides', {}, startTime);
-
-      expect(mockLogger.timing).toHaveBeenCalledWith('get_available_best_practice_guides', startTime);
-    });
-
-    it('should log execution details', async () => {
-      await handler.handle('get_available_best_practice_guides', {}, Date.now());
-
-      expect(mockLogger.debug).toHaveBeenCalledWith(
-        'get_available_best_practice_guides completed successfully',
-        expect.any(Object),
-      );
-    });
-  });
-});