sfcc-dev-mcp 1.0.15 → 1.0.19

package/src/utils/category-utils.ts

@@ -0,0 +1,70 @@
+/**
+ * Category Utilities
+ *
+ * Shared utilities for category-based document organization.
+ * Used by ISML, SFRA, and other documentation clients.
+ */
+
+export interface CategoryInfo {
+  displayName: string;
+  description: string;
+}
+
+export interface CategoryWithCount extends CategoryInfo {
+  name: string;
+  count?: number;
+}
+
+/**
+ * Get a category for an item based on mappings, with fallback
+ */
+export function getCategoryForItem<T extends string>(
+  itemName: string,
+  mappings: Record<string, T>,
+  fallback: T,
+): T {
+  return (mappings[itemName.toLowerCase()] ?? fallback) as T;
+}
+
+/**
+ * Build category list with counts from items
+ */
+export function buildCategoryList<T extends string>(
+  items: Array<{ category: T }>,
+  categoryDescriptions: Record<T, CategoryInfo>,
+): CategoryWithCount[] {
+  const categoryCounts = new Map<T, number>();
+
+  // Count elements per category
+  for (const item of items) {
+    const count = categoryCounts.get(item.category) ?? 0;
+    categoryCounts.set(item.category, count + 1);
+  }
+
+  // Build category info
+  const categories: CategoryWithCount[] = [];
+  for (const [categoryKey, count] of categoryCounts.entries()) {
+    const categoryInfo = categoryDescriptions[categoryKey];
+    if (categoryInfo) {
+      categories.push({
+        name: categoryKey,
+        displayName: categoryInfo.displayName,
+        description: categoryInfo.description,
+        count,
+      });
+    }
+  }
+
+  // Sort by display name
+  return categories.sort((a, b) => a.displayName.localeCompare(b.displayName));
+}
+
+/**
+ * Filter items by category
+ */
+export function filterByCategory<T extends { category: string }>(
+  items: T[],
+  category: string,
+): T[] {
+  return items.filter(item => item.category === category);
+}

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

@@ -3,14 +3,22 @@
  * Centralizes defaults, types, and configuration
  */
 
-// Log levels enum for type safety
-export enum LogLevel {
-  ERROR = 'error',
-  WARN = 'warn',
-  INFO = 'info',
-  DEBUG = 'debug',
-  ALL = 'all'
-}
+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 = {
@@ -52,15 +60,15 @@ export type JobLogToolName = 'get_latest_job_log_files' | 'search_job_logs_by_na
 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?: LogLevel; limit?: number; 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?: LogLevel; limit?: number; jobName?: string }
-  | { tool: 'search_job_logs'; pattern: string; level?: LogLevel; limit?: number; jobName?: string }
+  | { 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
@@ -68,20 +76,20 @@ export function getLimit(providedLimit: number | undefined, toolType: keyof type
   return providedLimit ?? DEFAULT_LIMITS[toolType];
 }
 
-export function isValidLogLevel(level: string): level is LogLevel {
-  return Object.values(LogLevel).includes(level as LogLevel);
+export function isValidLogLevel(level: string): level is LogLevelWithAll {
+  return Object.values(LogLevelValues).includes(level as LogLevelWithAll);
 }
 
-export function deriveLogLevel(toolName: string, argsLevel?: string): LogLevel {
+export function deriveLogLevel(toolName: string, argsLevel?: string): LogLevelWithAll {
   if (argsLevel && isValidLogLevel(argsLevel)) {
-    return argsLevel as LogLevel;
+    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 LogLevel;
+    return match[1] as LogLevelWithAll;
   }
 
-  return LogLevel.ALL;
+  return LogLevelValues.ALL;
 }

package/src/utils/logger.ts

@@ -87,15 +87,52 @@ export class Logger {
     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 fullMessage = args.length > 0 ? `${formattedMessage} ${args.map(arg =>
+    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`;

package/src/utils/markdown-utils.ts

@@ -0,0 +1,280 @@
+/**
+ * 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/path-resolver.ts

@@ -14,11 +14,34 @@ export class PathResolver {
    */
   static getCurrentWorkingDir(): string {
     // Get the directory of the current module file
+    // ts-jest may compile with a CommonJS module target in tests; suppress the
+    // diagnostic because runtime uses ESM (NodeNext) where import.meta is valid.
     const __filename = fileURLToPath(import.meta.url);
     const __dirname = path.dirname(__filename);
 
-    // Return the parent directory (project root)
-    return path.resolve(__dirname, '..');
+    // Return the project root (handles both src/ and dist/ locations)
+    return path.resolve(__dirname, '..', '..');
+  }
+
+  /**
+   * Root path for bundled AI instructions (AGENTS.md + skills)
+   */
+  static getAiInstructionsPath(): string {
+    return this.getRelativePath('ai-instructions');
+  }
+
+  /**
+   * Path to the bundled AGENTS.md
+   */
+  static getAgentsInstructionsFile(): string {
+    return path.join(this.getAiInstructionsPath(), 'AGENTS.md');
+  }
+
+  /**
+   * Path to the bundled skills directory
+   */
+  static getSkillsSourcePath(): string {
+    return path.join(this.getAiInstructionsPath(), 'skills');
   }
 
   /**
@@ -37,13 +60,6 @@ export class PathResolver {
     return this.getRelativePath('docs');
   }
 
-  /**
-   * Get the best practices docs directory path relative to the current working directory
-   */
-  static getBestPracticesPath(): string {
-    return this.getRelativePath('docs', 'best-practices');
-  }
-
   /**
    * Get the SFRA docs directory path relative to the current working directory
    */

package/src/utils/path-validation.ts

@@ -0,0 +1,113 @@
+/**
+ * Path Validation Utilities
+ *
+ * Provides secure path validation for file operations.
+ * Prevents path traversal attacks and validates file names.
+ */
+
+import * as path from 'path';
+
+export interface PathValidationOptions {
+  /** Allowed file extensions (e.g., ['.md', '.json']) */
+  allowedExtensions?: string[];
+  /** Whether to normalize the name to lowercase */
+  normalizeToLowerCase?: boolean;
+}
+
+export class PathValidationError extends Error {
+  constructor(message: string, public readonly code: string = 'PATH_VALIDATION_ERROR') {
+    super(message);
+    this.name = 'PathValidationError';
+  }
+}
+
+/**
+ * Validate a file/document name for security issues
+ * @param name - The name to validate
+ * @param fieldName - Human-readable field name for error messages
+ * @throws PathValidationError if validation fails
+ */
+export function validateFileName(name: string, fieldName: string = 'name'): void {
+  if (!name || typeof name !== 'string') {
+    throw new PathValidationError(`Invalid ${fieldName}: must be a non-empty string`, 'INVALID_TYPE');
+  }
+
+  // Prevent null bytes
+  if (name.includes('\0') || name.includes('\x00')) {
+    throw new PathValidationError(`Invalid ${fieldName}: contains null bytes`, 'NULL_BYTES');
+  }
+
+  // Prevent path traversal sequences
+  if (name.includes('..') || name.includes('/') || name.includes('\\')) {
+    throw new PathValidationError(`Invalid ${fieldName}: contains path traversal sequences`, 'PATH_TRAVERSAL');
+  }
+
+  // Only allow safe characters
+  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+    throw new PathValidationError(`Invalid ${fieldName}: contains invalid characters`, 'INVALID_CHARACTERS');
+  }
+}
+
+/**
+ * Construct and validate a file path within a base directory
+ * @param basePath - The base directory path
+ * @param fileName - The file name (without extension)
+ * @param options - Validation options
+ * @returns The validated, resolved file path
+ * @throws PathValidationError if validation fails
+ */
+export function constructValidatedPath(
+  basePath: string,
+  fileName: string,
+  options: PathValidationOptions = {},
+): string {
+  const { allowedExtensions = ['.md'], normalizeToLowerCase = true } = options;
+
+  // Validate the file name first
+  validateFileName(fileName, 'file name');
+
+  // Normalize if requested
+  const normalizedName = normalizeToLowerCase ? fileName.toLowerCase() : fileName;
+
+  // Determine extension (use first allowed extension by default)
+  const extension = allowedExtensions[0] ?? '.md';
+
+  // Construct the path
+  const filePath = path.join(basePath, `${normalizedName}${extension}`);
+  const resolvedPath = path.resolve(filePath);
+  const resolvedBasePath = path.resolve(basePath);
+
+  // Ensure the path is within the base directory
+  if (!resolvedPath.startsWith(resolvedBasePath)) {
+    throw new PathValidationError('Invalid file name: path outside allowed directory', 'OUTSIDE_BASE_DIR');
+  }
+
+  // Ensure the file has the correct extension
+  const hasValidExtension = allowedExtensions.some(ext =>
+    resolvedPath.toLowerCase().endsWith(ext.toLowerCase()),
+  );
+  if (!hasValidExtension) {
+    throw new PathValidationError(
+      `Invalid file name: must reference a ${allowedExtensions.join(' or ')} file`,
+      'INVALID_EXTENSION',
+    );
+  }
+
+  return resolvedPath;
+}
+
+/**
+ * Validate binary content
+ * @param content - The content to validate
+ * @param fieldName - Human-readable field name for error messages
+ * @throws PathValidationError if content appears to be binary
+ */
+export function validateTextContent(content: string, fieldName: string = 'content'): void {
+  if (!content.trim()) {
+    throw new PathValidationError(`Empty ${fieldName}`, 'EMPTY_CONTENT');
+  }
+
+  if (content.includes('\0')) {
+    throw new PathValidationError(`Invalid ${fieldName}: contains binary data`, 'BINARY_CONTENT');
+  }
+}

package/tests/base-handler.test.ts

@@ -365,7 +365,7 @@ describe('BaseToolHandler', () => {
       await handler.handle('test_tool', {}, Date.now());
 
       expect(mockLogger.debug).toHaveBeenCalledWith(
-        'test_tool completed successfully',
+        'test_tool completed',
         expect.any(Object),
       );
     });

package/tests/cache.test.ts

@@ -361,9 +361,9 @@ describe('CacheManager', () => {
 
       cacheManager.destroy();
 
-      // After destroy, the caches should be cleared
+      // After destroy, the caches map should be cleared (empty stats object)
       allStats = cacheManager.getAllStats();
-      expect(allStats.fileContent.size).toBe(0);
+      expect(Object.keys(allStats).length).toBe(0);
     });
   });