sfcc-dev-mcp 1.0.19 → 1.0.20

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

@@ -1,95 +0,0 @@
-/**
- * Shared constants for log tool handlers
- * Centralizes defaults, types, and configuration
- */
-
-import type { LogLevel as BaseLogLevel } from '../types/types.js';
-
-// Extended log level type that includes 'all' for tool filtering
-export type LogLevelWithAll = BaseLogLevel | 'all';
-
-// Re-export base LogLevel for convenience
-export type { LogLevel } from '../types/types.js';
-
-// Log levels enum for validation and iteration
-export const LogLevelValues = {
-  ERROR: 'error',
-  WARN: 'warn',
-  INFO: 'info',
-  DEBUG: 'debug',
-  ALL: 'all',
-} as const;
-
-// Default limits for different tool types
-export const DEFAULT_LIMITS = {
-  latest: 10,
-  search: 20,
-  jobEntries: 50,
-  jobSearch: 20,
-  jobFiles: 10,
-} as const;
-
-// Tool name sets for O(1) lookup
-export const LOG_TOOL_NAMES_SET = new Set([
-  'get_latest_error',
-  'get_latest_warn',
-  'get_latest_info',
-  'get_latest_debug',
-  'summarize_logs',
-  'search_logs',
-  'list_log_files',
-  'get_log_file_contents',
-] as const);
-
-export const JOB_LOG_TOOL_NAMES_SET = new Set([
-  'get_latest_job_log_files',
-  'search_job_logs_by_name',
-  'get_job_log_entries',
-  'search_job_logs',
-  'get_job_execution_summary',
-] as const);
-
-// Type definitions
-export type LogToolName = 'get_latest_error' | 'get_latest_warn' | 'get_latest_info' | 'get_latest_debug' |
-                         'summarize_logs' | 'search_logs' | 'list_log_files' | 'get_log_file_contents';
-
-export type JobLogToolName = 'get_latest_job_log_files' | 'search_job_logs_by_name' | 'get_job_log_entries' |
-                            'search_job_logs' | 'get_job_execution_summary';
-
-// Typed argument interfaces for each tool
-export type LogToolArgs =
-  | { tool: 'get_latest_error' | 'get_latest_warn' | 'get_latest_info' | 'get_latest_debug'; limit?: number; date?: string }
-  | { tool: 'summarize_logs'; date?: string }
-  | { tool: 'search_logs'; pattern: string; logLevel?: LogLevelWithAll; limit?: number; date?: string }
-  | { tool: 'list_log_files' }
-  | { tool: 'get_log_file_contents'; filename: string; maxBytes?: number; tailOnly?: boolean };
-
-export type JobLogToolArgs =
-  | { tool: 'get_latest_job_log_files'; limit?: number }
-  | { tool: 'search_job_logs_by_name'; jobName: string; limit?: number }
-  | { tool: 'get_job_log_entries'; level?: LogLevelWithAll; limit?: number; jobName?: string }
-  | { tool: 'search_job_logs'; pattern: string; level?: LogLevelWithAll; limit?: number; jobName?: string }
-  | { tool: 'get_job_execution_summary'; jobName: string };
-
-// Helper functions
-export function getLimit(providedLimit: number | undefined, toolType: keyof typeof DEFAULT_LIMITS): number {
-  return providedLimit ?? DEFAULT_LIMITS[toolType];
-}
-
-export function isValidLogLevel(level: string): level is LogLevelWithAll {
-  return Object.values(LogLevelValues).includes(level as LogLevelWithAll);
-}
-
-export function deriveLogLevel(toolName: string, argsLevel?: string): LogLevelWithAll {
-  if (argsLevel && isValidLogLevel(argsLevel)) {
-    return argsLevel as LogLevelWithAll;
-  }
-
-  // Extract level from tool name for get_latest_* tools
-  const match = toolName.match(/get_latest_(\w+)/);
-  if (match && isValidLogLevel(match[1])) {
-    return match[1] as LogLevelWithAll;
-  }
-
-  return LogLevelValues.ALL;
-}

package/src/utils/logger.ts

@@ -1,260 +0,0 @@
-/**
- * Logger class for standardized logging across the SFCC MCP application.
- * Provides consistent logging with timestamps and log levels.
- * Always logs to files for consistent debugging and to avoid interfering with stdio.
- *
- * ## Log Directory Location
- *
- * The logger uses the operating system's temporary directory via Node.js `os.tmpdir()`:
- * - **macOS**: `/var/folders/{user-specific-path}/T/sfcc-mcp-logs/`
- * - **Linux**: `/tmp/sfcc-mcp-logs/` (typically)
- * - **Windows**: `%TEMP%\sfcc-mcp-logs\` (typically `C:\Users\{user}\AppData\Local\Temp\`)
- *
- * This approach provides:
- * - User-specific isolation (more secure than system-wide `/tmp`)
- * - Automatic cleanup by the OS
- * - Platform-appropriate temporary storage
- * - Proper permissions handling
- *
- * To find your log directory, use `Logger.getInstance().getLogDirectory()` or check
- * the debug logs which show the directory path during initialization.
- */
-
-import { appendFileSync, existsSync, mkdirSync } from 'fs';
-import { join } from 'path';
-import { tmpdir } from 'os';
-
-export class Logger {
-  private context: string;
-  private enableTimestamp: boolean;
-  private debugEnabled: boolean;
-  private logDir: string;
-  private static instance: Logger | null = null;
-
-  /**
-   * Create a new Logger instance
-   * @param context The context/component name for this logger
-   * @param enableTimestamp Whether to include timestamps in log messages (default: true)
-   * @param debugEnabled Whether to enable debug logging (default: false)
-   * @param customLogDir Custom log directory for testing purposes
-   */
-  constructor(context: string = 'SFCC-MCP', enableTimestamp: boolean = true, debugEnabled: boolean = false, customLogDir?: string) {
-    this.context = context;
-    this.enableTimestamp = enableTimestamp;
-    this.debugEnabled = debugEnabled;
-
-    // Set up log directory - use custom directory for testing or default for production
-    this.logDir = customLogDir ?? join(tmpdir(), 'sfcc-mcp-logs');
-    if (!existsSync(this.logDir)) {
-      mkdirSync(this.logDir, { recursive: true });
-    }
-  }
-
-  /**
-   * Initialize the global logger instance with specific settings
-   * This should be called once at application startup
-   */
-  public static initialize(context: string = 'SFCC-MCP', enableTimestamp: boolean = true, debugEnabled: boolean = false, customLogDir?: string): void {
-    Logger.instance = new Logger(context, enableTimestamp, debugEnabled, customLogDir);
-  }
-
-  /**
-   * Get the global logger instance
-   * If not initialized, creates a default instance
-   */
-  public static getInstance(): Logger {
-    Logger.instance ??= new Logger();
-    return Logger.instance;
-  }
-
-  /**
-   * Create a child logger with a new context but inheriting other settings from the global instance
-   * @param subContext The sub-context to append to the current context
-   * @returns A new Logger instance with the combined context
-   */
-  public static getChildLogger(subContext: string): Logger {
-    const globalLogger = Logger.getInstance();
-    return new Logger(`${globalLogger.context}:${subContext}`, globalLogger.enableTimestamp, globalLogger.debugEnabled, globalLogger.logDir);
-  }
-
-  /**
-   * Format a log message with optional timestamp and context
-   * @param message The message to format
-   * @returns Formatted message string
-   */
-  private formatMessage(message: string): string {
-    const timestamp = this.enableTimestamp ? `[${new Date().toISOString()}] ` : '';
-    return `${timestamp}[${this.context}] ${message}`;
-  }
-
-  /**
-   * Patterns for sensitive data that should be masked in logs
-   * These patterns match common credential formats to prevent accidental leakage
-   */
-  private static readonly SENSITIVE_PATTERNS: Array<{ pattern: RegExp; replacement: string }> = [
-    // Password fields in JSON
-    { pattern: /"password"\s*:\s*"[^"]+"/gi, replacement: '"password": "[REDACTED]"' },
-    // Client secret fields in JSON
-    { pattern: /"client[-_]?secret"\s*:\s*"[^"]+"/gi, replacement: '"client-secret": "[REDACTED]"' },
-    { pattern: /"clientSecret"\s*:\s*"[^"]+"/gi, replacement: '"clientSecret": "[REDACTED]"' },
-    // Access tokens
-    { pattern: /"access[-_]?token"\s*:\s*"[^"]+"/gi, replacement: '"access_token": "[REDACTED]"' },
-    { pattern: /"accessToken"\s*:\s*"[^"]+"/gi, replacement: '"accessToken": "[REDACTED]"' },
-    // Bearer tokens in Authorization headers
-    { pattern: /Bearer\s+[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]*/gi, replacement: 'Bearer [REDACTED]' },
-    // Basic auth headers
-    { pattern: /Basic\s+[A-Za-z0-9+/=]+/gi, replacement: 'Basic [REDACTED]' },
-    // API keys
-    { pattern: /"api[-_]?key"\s*:\s*"[^"]+"/gi, replacement: '"api_key": "[REDACTED]"' },
-  ];
-
-  /**
-   * Mask sensitive data in log messages
-   * @param text The text to sanitize
-   * @returns Sanitized text with sensitive data masked
-   */
-  private maskSensitiveData(text: string): string {
-    let sanitized = text;
-    for (const { pattern, replacement } of Logger.SENSITIVE_PATTERNS) {
-      sanitized = sanitized.replace(pattern, replacement);
-    }
-    return sanitized;
-  }
-
-  /**
-   * Write log message to appropriate log file
-   */
-  private writeLog(level: 'info' | 'warn' | 'error' | 'debug', message: string, ...args: any[]): void {
-    const formattedMessage = this.formatMessage(message);
-    const rawFullMessage = args.length > 0 ? `${formattedMessage} ${args.map(arg =>
-      typeof arg === 'object' ? JSON.stringify(arg, null, 2) : String(arg),
-    ).join(' ')}` : formattedMessage;
-
-    // Apply sensitive data masking before writing to log
-    const fullMessage = this.maskSensitiveData(rawFullMessage);
-
-    // Always write to log files
-    const logFile = join(this.logDir, `sfcc-mcp-${level}.log`);
-    const logEntry = `${fullMessage}\n`;
-
-    try {
-      appendFileSync(logFile, logEntry, 'utf8');
-    } catch (error) {
-      // Fallback: if file logging fails, try stderr for critical errors only
-      if (level === 'error') {
-        process.stderr.write(`[LOGGER ERROR] Could not write to log file: ${error}\n`);
-        process.stderr.write(`${logEntry}`);
-      }
-    }
-  }
-
-  /**
-   * Log an informational message
-   * @param message The message to log
-   * @param args Optional arguments to include
-   */
-  public log(message: string, ...args: any[]): void {
-    this.writeLog('info', message, ...args);
-  }
-
-  /**
-   * Log an informational message (alias for log)
-   * @param message The message to log
-   * @param args Optional arguments to include
-   */
-  public info(message: string, ...args: any[]): void {
-    this.writeLog('info', message, ...args);
-  }
-
-  /**
-   * Log a warning message
-   * @param message The warning message to log
-   * @param args Optional arguments to include
-   */
-  public warn(message: string, ...args: any[]): void {
-    this.writeLog('warn', message, ...args);
-  }
-
-  /**
-   * Log an error message
-   * @param message The error message to log
-   * @param args Optional arguments to include
-   */
-  public error(message: string, ...args: any[]): void {
-    this.writeLog('error', message, ...args);
-  }
-
-  /**
-   * Log a debug message (only if debug is enabled)
-   * @param message The debug message to log
-   * @param args Optional arguments to include
-   */
-  public debug(message: string, ...args: any[]): void {
-    if (this.debugEnabled) {
-      this.writeLog('debug', `[DEBUG] ${message}`, ...args);
-    }
-  }
-
-  /**
-   * Log method entry with parameters
-   * @param methodName The name of the method being entered
-   * @param params Optional parameters being passed to the method
-   */
-  public methodEntry(methodName: string, params?: any): void {
-    if (this.debugEnabled) {
-      const paramStr = params ? ` with params: ${JSON.stringify(params)}` : '';
-      this.debug(`Entering method: ${methodName}${paramStr}`);
-    }
-  }
-
-  /**
-   * Log method exit with optional result
-   * @param methodName The name of the method being exited
-   * @param result Optional result being returned from the method
-   */
-  public methodExit(methodName: string, result?: any): void {
-    if (this.debugEnabled) {
-      const resultStr = result !== undefined ? ` with result: ${typeof result === 'object' ? JSON.stringify(result) : result}` : '';
-      this.debug(`Exiting method: ${methodName}${resultStr}`);
-    }
-  }
-
-  /**
-   * Log performance timing information
-   * @param operation The operation being timed
-   * @param startTime The start time (from performance.now() or Date.now())
-   */
-  public timing(operation: string, startTime: number): void {
-    if (this.debugEnabled) {
-      const duration = Date.now() - startTime;
-      this.debug(`Performance: ${operation} took ${duration}ms`);
-    }
-  }
-
-  /**
-   * Create a child logger with a new context but inheriting other settings
-   * @param subContext The sub-context to append to the current context
-   * @returns A new Logger instance with the combined context
-   */
-  public createChildLogger(subContext: string): Logger {
-    return new Logger(`${this.context}:${subContext}`, this.enableTimestamp, this.debugEnabled, this.logDir);
-  }
-
-  /**
-   * Enable or disable debug logging
-   * @param enabled Whether debug logging should be enabled
-   */
-  public setDebugEnabled(enabled: boolean): void {
-    this.debugEnabled = enabled;
-  }
-
-  /**
-   * Get the current log directory
-   */
-  public getLogDirectory(): string {
-    return this.logDir;
-  }
-}
-
-// Export the singleton instance getter for convenience
-export const getLogger = Logger.getInstance;

package/src/utils/markdown-utils.ts

@@ -1,280 +0,0 @@
-/**
- * Markdown Document Utilities
- *
- * Shared utilities for parsing and extracting content from markdown documentation files.
- * Used by SFRA and ISML clients to avoid code duplication.
- */
-
-/**
- * Extract description from markdown content
- * Looks for Overview section first, then falls back to first paragraph after title
- */
-export function extractDescriptionFromContent(content: string): string {
-  // Look for Overview section
-  const overviewMatch = content.match(/##\s+Overview\s+(.+?)(?=\n##|\n\*\*|$)/s);
-  if (overviewMatch) {
-    const firstPara = overviewMatch[1].trim().split('\n\n')[0];
-    return firstPara.replace(/\n/g, ' ').trim();
-  }
-
-  // Fallback to first paragraph after title
-  const firstParaMatch = content.match(/^#.+?\n\n(.+?)(?=\n\n|$)/s);
-  if (firstParaMatch) {
-    return firstParaMatch[1].replace(/\n/g, ' ').trim();
-  }
-
-  return '';
-}
-
-/**
- * Extract description from lines array with optional title context
- */
-export function extractDescriptionFromLines(lines: string[], title?: string): string {
-  const titleIndex = title
-    ? lines.findIndex(line => line.trim() === `# ${title}` || line.startsWith('#'))
-    : lines.findIndex(line => line.startsWith('#'));
-
-  if (titleIndex === -1) {
-    return 'No description available';
-  }
-
-  // Look for overview section first
-  const overviewIndex = lines.findIndex((line, index) =>
-    index > titleIndex && line.toLowerCase().includes('## overview'),
-  );
-
-  if (overviewIndex !== -1) {
-    let descriptionEnd = lines.findIndex((line, index) =>
-      index > overviewIndex + 1 && line.startsWith('##'),
-    );
-
-    if (descriptionEnd === -1) {
-      descriptionEnd = Math.min(lines.length, overviewIndex + 10);
-    }
-
-    const overviewContent = lines.slice(overviewIndex + 1, descriptionEnd)
-      .filter(line => line.trim() && !line.startsWith('#'))
-      .join(' ')
-      .trim();
-
-    if (overviewContent) {
-      return truncateWithEllipsis(overviewContent, 300);
-    }
-  }
-
-  // Fallback to first paragraph after title
-  let descriptionStart = titleIndex + 1;
-  while (descriptionStart < lines.length && !lines[descriptionStart].trim()) {
-    descriptionStart++;
-  }
-
-  const descriptionEnd = lines.findIndex((line, index) =>
-    index > descriptionStart && (line.startsWith('#') || line.trim() === ''));
-
-  const description = lines
-    .slice(descriptionStart, descriptionEnd > -1 ? descriptionEnd : descriptionStart + 3)
-    .filter(line => line.trim() && !line.startsWith('#'))
-    .join(' ')
-    .trim();
-
-  return description || 'No description available';
-}
-
-/**
- * Extract section headings from markdown content
- */
-export function extractSections(content: string, headingLevel: number = 2): string[] {
-  const prefix = '#'.repeat(headingLevel);
-  // Use negative lookahead to ensure we don't match more # than specified
-  const regex = new RegExp(`^${prefix}(?!#)\\s+(.+)$`, 'gm');
-  const sections: string[] = [];
-  let match;
-
-  while ((match = regex.exec(content)) !== null) {
-    sections.push(match[1].trim());
-  }
-
-  return sections;
-}
-
-/**
- * Extract properties from document content (### headings in a Properties section)
- */
-export function extractProperties(lines: string[]): string[] {
-  return extractSectionItems(lines, ['## properties', '## property']);
-}
-
-/**
- * Extract methods from document content (### headings in a Methods section)
- */
-export function extractMethods(lines: string[]): string[] {
-  return extractSectionItems(lines, ['## method', '## function', '## methods', '## functions']);
-}
-
-/**
- * Generic extraction of ### items from specific ## sections
- */
-function extractSectionItems(lines: string[], sectionPatterns: string[]): string[] {
-  const items: string[] = [];
-  let inSection = false;
-
-  for (const line of lines) {
-    const lineLower = line.toLowerCase();
-
-    // Check if we're entering the target section
-    if (sectionPatterns.some(pattern => lineLower.includes(pattern))) {
-      inSection = true;
-      continue;
-    }
-
-    // Check if we're leaving the section (hit another ## heading)
-    if (inSection && line.startsWith('## ') &&
-        !sectionPatterns.some(pattern => lineLower.includes(pattern.replace('## ', '')))) {
-      break;
-    }
-
-    // Extract ### items
-    if (inSection && line.startsWith('### ')) {
-      const item = line.replace('### ', '').trim();
-      if (!items.includes(item)) {
-        items.push(item);
-      }
-    }
-  }
-
-  return items;
-}
-
-/**
- * Truncate text with ellipsis
- */
-export function truncateWithEllipsis(text: string, maxLength: number): string {
-  if (text.length <= maxLength) {
-    return text;
-  }
-  return `${text.substring(0, maxLength)}...`;
-}
-
-/**
- * Calculate search relevance score for a document
- */
-export function calculateSearchRelevance(
-  searchQuery: string,
-  fields: {
-    name?: string;
-    title?: string;
-    description?: string;
-    sections?: string[];
-    content?: string;
-    attributes?: string[];
-  },
-  weights: {
-    nameExact?: number;
-    namePartial?: number;
-    title?: number;
-    description?: number;
-    section?: number;
-    content?: number;
-    contentMax?: number;
-    attribute?: number;
-  } = {},
-): number {
-  const {
-    nameExact = 150,
-    namePartial = 100,
-    title = 50,
-    description = 30,
-    section = 10,
-    content = 2,
-    contentMax = 20,
-    attribute = 15,
-  } = weights;
-
-  const lowerQuery = searchQuery.toLowerCase();
-  let score = 0;
-
-  // Name match (highest priority)
-  if (fields.name) {
-    const lowerName = fields.name.toLowerCase();
-    if (lowerName === lowerQuery) {
-      score += nameExact;
-    } else if (lowerName.includes(lowerQuery)) {
-      score += namePartial;
-    }
-  }
-
-  // Title match
-  if (fields.title?.toLowerCase().includes(lowerQuery)) {
-    score += title;
-  }
-
-  // Description match
-  if (fields.description?.toLowerCase().includes(lowerQuery)) {
-    score += description;
-  }
-
-  // Section name match
-  if (fields.sections) {
-    for (const s of fields.sections) {
-      if (s.toLowerCase().includes(lowerQuery)) {
-        score += section;
-      }
-    }
-  }
-
-  // Content match (lower priority, capped)
-  if (fields.content) {
-    const matches = (fields.content.toLowerCase().match(new RegExp(lowerQuery, 'g')) ?? []).length;
-    score += Math.min(matches * content, contentMax);
-  }
-
-  // Attribute match
-  if (fields.attributes) {
-    for (const attr of fields.attributes) {
-      if (attr.toLowerCase().includes(lowerQuery)) {
-        score += attribute;
-      }
-    }
-  }
-
-  return score;
-}
-
-/**
- * Generate a preview snippet around a search match
- */
-export function generateSearchPreview(content: string, query: string, contextChars: number = 100): string {
-  const lowerContent = content.toLowerCase();
-  const lowerQuery = query.toLowerCase();
-
-  const index = lowerContent.indexOf(lowerQuery);
-  if (index === -1) {
-    return content.slice(0, contextChars * 2);
-  }
-
-  const start = Math.max(0, index - contextChars);
-  const end = Math.min(content.length, index + query.length + contextChars);
-  let preview = content.slice(start, end);
-
-  // Clean up and add ellipsis
-  preview = preview.replace(/\n/g, ' ').replace(/\s+/g, ' ').trim();
-
-  if (start > 0) {
-    preview = `...${preview}`;
-  }
-  if (end < content.length) {
-    preview = `${preview}...`;
-  }
-
-  return preview;
-}
-
-/**
- * Format a document name for display (kebab-case to Title Case)
- */
-export function formatDocumentName(documentName: string): string {
-  return documentName
-    .split('-')
-    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
-    .join(' ');
-}

package/src/utils/ocapi-url-builder.ts

@@ -1,48 +0,0 @@
-/**
- * OCAPI URL Builder Utility
- *
- * Provides centralized URL construction for OCAPI endpoints with support for
- * LOCAL_OCAPI_MOCK_URL environment variable override for testing.
- */
-
-import { OCAPIConfig } from '../types/types.js';
-
-/**
- * Build the base URL for OCAPI Data API endpoints
- *
- * @param config - OCAPI configuration object
- * @returns Base URL for OCAPI Data API endpoints
- */
-export function buildOCAPIBaseUrl(config: OCAPIConfig): string {
-  const version = config.version ?? 'v23_2';
-  const hostname = config.hostname;
-
-  // Check if hostname is localhost (with or without port) for HTTP protocol
-  if (hostname === 'localhost' || hostname.startsWith('localhost:')) {
-    const protocol = hostname.includes('://') ? '' : 'http://';
-    return `${protocol}${hostname}/s/-/dw/data/${version}`;
-  }
-
-  // For live SFCC instances, use HTTPS
-  return `https://${hostname}/s/-/dw/data/${version}`;
-}
-
-/**
- * Build the OAuth token URL for OCAPI authentication
- *
- * @param config - OCAPI configuration object
- * @returns OAuth token endpoint URL
- */
-export function buildOCAPIAuthUrl(config: OCAPIConfig): string {
-  const hostname = config.hostname;
-
-  // Check if hostname is localhost (with or without port) for fallback
-  if (hostname === 'localhost' || hostname.startsWith('localhost:')) {
-    // For localhost, use the same host and add the auth endpoint path
-    const protocol = hostname.includes('://') ? '' : 'http://';
-    return `${protocol}${hostname}/dwsso/oauth2/access_token`;
-  }
-
-  // For live SFCC instances, use the default Demandware auth URL
-  return 'https://account.demandware.com/dwsso/oauth2/access_token';
-}