sfcc-dev-mcp 1.0.15 → 1.0.19

package/src/clients/base/abstract-documentation-client.ts

@@ -0,0 +1,405 @@
+/**
+ * Abstract Documentation Client
+ *
+ * Base class for documentation clients (SFRA, ISML) that share common patterns:
+ * - Category-based organization
+ * - Caching with TTL
+ * - Search with relevance scoring
+ * - File-based document loading
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { CacheManager } from '../../utils/cache.js';
+import { Logger } from '../../utils/logger.js';
+import {
+  extractDescriptionFromContent,
+  extractSections,
+  calculateSearchRelevance,
+  generateSearchPreview,
+} from '../../utils/markdown-utils.js';
+import { buildCategoryList, CategoryInfo } from '../../utils/category-utils.js';
+
+/**
+ * Base document interface - extend for specific document types
+ */
+export interface BaseDocument {
+  name: string;
+  title: string;
+  description: string;
+  sections: string[];
+  content: string;
+  category: string;
+  filename: string;
+  lastModified?: Date;
+}
+
+/**
+ * Summary format for document lists
+ */
+export interface DocumentSummary {
+  name: string;
+  title: string;
+  description: string;
+  category: string;
+  filename: string;
+}
+
+/**
+ * Search result with relevance scoring
+ */
+export interface SearchResult<T extends DocumentSummary> {
+  document: T;
+  relevance: number;
+  matchedSections: string[];
+  preview: string;
+}
+
+/**
+ * Category information with count
+ */
+export interface CategoryWithCount {
+  name: string;
+  displayName: string;
+  description: string;
+  count: number;
+}
+
+/**
+ * Configuration for the documentation client
+ */
+export interface DocumentationClientConfig<TCategory extends string> {
+  /** Name for logging */
+  clientName: string;
+  /** Path to documentation files */
+  docsPath: string;
+  /** Category mappings (document name -> category) */
+  categoryMappings: Record<string, TCategory>;
+  /** Category descriptions */
+  categoryDescriptions: Record<TCategory, CategoryInfo>;
+  /** Default category for unmapped documents */
+  defaultCategory: TCategory;
+  /** Cache key prefix */
+  cachePrefix: string;
+}
+
+/**
+ * Abstract base class for documentation clients
+ * Provides common functionality for loading, caching, and searching documents
+ */
+export abstract class AbstractDocumentationClient<
+  TDocument extends BaseDocument,
+  TSummary extends DocumentSummary,
+  TCategory extends string,
+> {
+  protected readonly logger: Logger;
+  protected readonly cache: CacheManager;
+  protected readonly docsPath: string;
+  protected readonly config: DocumentationClientConfig<TCategory>;
+  protected documentsCache: TDocument[] | null = null;
+  protected lastScanTime: number = 0;
+  protected static readonly SCAN_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+
+  constructor(config: DocumentationClientConfig<TCategory>) {
+    this.config = config;
+    this.logger = Logger.getChildLogger(config.clientName);
+    this.cache = new CacheManager();
+    this.docsPath = config.docsPath;
+  }
+
+  /**
+   * Get list of all available documents with summaries
+   */
+  async getAvailableDocuments(): Promise<TSummary[]> {
+    this.logger.debug('Getting available documents');
+
+    const cacheKey = `${this.config.cachePrefix}:documents:list`;
+    const now = Date.now();
+
+    // Check cache validity
+    if (this.documentsCache && (now - this.lastScanTime) < AbstractDocumentationClient.SCAN_CACHE_TTL) {
+      const cached = this.cache.getSearchResults(cacheKey);
+      if (cached) {
+        return cached;
+      }
+    }
+
+    const documents = await this.loadAllDocuments();
+    const summaries = documents.map(doc => this.toSummary(doc));
+
+    // Sort by category and name
+    summaries.sort((a, b) => {
+      if (a.category !== b.category) {
+        return a.category.localeCompare(b.category);
+      }
+      return a.name.localeCompare(b.name);
+    });
+
+    this.cache.setSearchResults(cacheKey, summaries);
+    this.lastScanTime = now;
+
+    return summaries;
+  }
+
+  /**
+   * Get a specific document by name
+   */
+  async getDocument(documentName: string): Promise<TDocument | null> {
+    const normalizedName = this.normalizeDocumentName(documentName);
+    this.logger.debug(`Getting document: ${normalizedName}`);
+
+    const cacheKey = `${this.config.cachePrefix}:document:${normalizedName}`;
+    const cached = this.cache.getSearchResults(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    const documents = await this.loadAllDocuments();
+    const document = documents.find(doc =>
+      doc.name.toLowerCase() === normalizedName.toLowerCase(),
+    );
+
+    if (!document) {
+      this.logger.warn(`Document not found: ${normalizedName}`);
+      return null;
+    }
+
+    this.cache.setSearchResults(cacheKey, document);
+    return document;
+  }
+
+  /**
+   * Search documents with relevance scoring
+   */
+  async searchDocuments(
+    query: string,
+    options?: { category?: string; limit?: number },
+  ): Promise<SearchResult<TSummary>[]> {
+    this.logger.debug(`Searching documents for: ${query}`);
+
+    const documents = await this.loadAllDocuments();
+    const searchQuery = query.toLowerCase();
+    const results: SearchResult<TSummary>[] = [];
+
+    for (const document of documents) {
+      // Skip if category filter doesn't match
+      if (options?.category && document.category !== options.category) {
+        continue;
+      }
+
+      const relevance = this.calculateDocumentRelevance(document, searchQuery);
+      if (relevance > 0) {
+        const matchedSections = this.findMatchedSections(document, searchQuery);
+        const preview = this.generateDocumentPreview(document, searchQuery);
+
+        results.push({
+          document: this.toSummary(document),
+          relevance,
+          matchedSections,
+          preview,
+        });
+      }
+    }
+
+    // Sort by relevance (highest first)
+    results.sort((a, b) => b.relevance - a.relevance);
+
+    // Apply limit if specified
+    return options?.limit ? results.slice(0, options.limit) : results;
+  }
+
+  /**
+   * Get documents filtered by category
+   */
+  async getDocumentsByCategory(category: string): Promise<TSummary[]> {
+    this.logger.debug(`Getting documents by category: ${category}`);
+
+    const documents = await this.loadAllDocuments();
+    return documents
+      .filter(doc => doc.category === category)
+      .map(doc => this.toSummary(doc));
+  }
+
+  /**
+   * Get available categories with counts
+   */
+  async getAvailableCategories(): Promise<CategoryWithCount[]> {
+    this.logger.debug('Getting available categories');
+
+    const cacheKey = `${this.config.cachePrefix}:categories`;
+    const cached = this.cache.getSearchResults(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    const documents = await this.loadAllDocuments();
+    // Cast documents to the expected type - we know category will be TCategory since
+    // documents are created with that constraint via createDocument and getCategoryForItem
+    const categoryList = buildCategoryList(
+      documents as unknown as Array<{ category: TCategory }>,
+      this.config.categoryDescriptions,
+    );
+
+    const categories: CategoryWithCount[] = categoryList.map(cat => ({
+      name: cat.name,
+      displayName: cat.displayName,
+      description: cat.description,
+      count: cat.count ?? 0,
+    }));
+
+    this.cache.setSearchResults(cacheKey, categories);
+    return categories;
+  }
+
+  /**
+   * Clear all caches
+   */
+  clearCache(): void {
+    this.cache.clearAll();
+    this.documentsCache = null;
+    this.lastScanTime = 0;
+  }
+
+  // ==================== Protected methods for subclass customization ====================
+
+  // Batch size for parallel file reads (avoid file descriptor exhaustion)
+  protected static readonly PARALLEL_BATCH_SIZE = 30;
+
+  /**
+   * Load all documents from the docs directory
+   * Uses parallel batch processing for improved performance
+   */
+  protected async loadAllDocuments(): Promise<TDocument[]> {
+    if (this.documentsCache) {
+      return this.documentsCache;
+    }
+
+    this.logger.debug(`Scanning documentation directory: ${this.docsPath}`);
+
+    try {
+      const files = await fs.readdir(this.docsPath);
+      const mdFiles = files.filter(f =>
+        f.endsWith('.md') &&
+        !f.startsWith('.') &&
+        f !== 'README.md',
+      );
+
+      this.logger.debug(`Found ${mdFiles.length} documentation files`);
+
+      // Process files in parallel batches for faster loading
+      const documents: TDocument[] = [];
+      for (let i = 0; i < mdFiles.length; i += AbstractDocumentationClient.PARALLEL_BATCH_SIZE) {
+        const batch = mdFiles.slice(i, i + AbstractDocumentationClient.PARALLEL_BATCH_SIZE);
+        const results = await Promise.all(
+          batch.map(async file => {
+            const filePath = path.join(this.docsPath, file);
+            return this.parseDocumentFile(filePath, file);
+          }),
+        );
+        // Filter out null results and add to documents
+        for (const result of results) {
+          if (result) {
+            documents.push(result);
+          }
+        }
+      }
+
+      this.documentsCache = documents;
+      return documents;
+    } catch (error) {
+      this.logger.error(`Error loading documents: ${error}`);
+      throw new Error(`Failed to load documentation: ${error}`);
+    }
+  }
+
+  /**
+   * Parse a single document file - override for custom parsing
+   */
+  protected async parseDocumentFile(filePath: string, filename: string): Promise<TDocument | null> {
+    try {
+      const content = await fs.readFile(filePath, 'utf-8');
+      const stats = await fs.stat(filePath);
+
+      const documentName = filename.replace('.md', '');
+      const normalizedName = this.normalizeDocumentName(documentName);
+
+      // Extract title from first heading
+      const titleMatch = content.match(/^#\s+(.+)$/m);
+      const title = titleMatch ? titleMatch[1].trim() : documentName;
+
+      // Get category
+      const category = this.config.categoryMappings[normalizedName] ?? this.config.defaultCategory;
+
+      // Use base document creation
+      return this.createDocument({
+        name: documentName,
+        title,
+        description: extractDescriptionFromContent(content),
+        sections: extractSections(content, 2),
+        content,
+        category,
+        filename,
+        lastModified: stats.mtime,
+      });
+    } catch (error) {
+      this.logger.error(`Error parsing document file ${filename}: ${error}`);
+      return null;
+    }
+  }
+
+  /**
+   * Create a document instance - override for custom document types
+   */
+  protected abstract createDocument(baseData: BaseDocument): TDocument;
+
+  /**
+   * Convert document to summary - override for custom summary types
+   */
+  protected abstract toSummary(document: TDocument): TSummary;
+
+  /**
+   * Normalize document name for consistent lookup
+   */
+  protected normalizeDocumentName(name: string): string {
+    return name.toLowerCase();
+  }
+
+  /**
+   * Calculate relevance score for a document
+   */
+  protected calculateDocumentRelevance(document: TDocument, query: string): number {
+    return calculateSearchRelevance(query, {
+      name: document.name,
+      title: document.title,
+      description: document.description,
+      sections: document.sections,
+      content: document.content,
+    });
+  }
+
+  /**
+   * Find sections that match the search query
+   */
+  protected findMatchedSections(document: TDocument, query: string): string[] {
+    const matched: string[] = [];
+    const lowerQuery = query.toLowerCase();
+
+    for (const section of document.sections) {
+      if (section.toLowerCase().includes(lowerQuery)) {
+        matched.push(section);
+      }
+    }
+
+    return matched;
+  }
+
+  /**
+   * Generate a preview snippet for search results
+   */
+  protected generateDocumentPreview(document: TDocument, query: string): string {
+    if (!document.content.toLowerCase().includes(query.toLowerCase())) {
+      return document.description.slice(0, 200);
+    }
+    return generateSearchPreview(document.content, query, 100);
+  }
+}

package/src/clients/base/oauth-token.ts

@@ -3,6 +3,12 @@
  *
  * This module provides a singleton Token class that manages OAuth 2.0 access tokens
  * for SFCC OCAPI requests. It handles automatic token refresh when tokens expire.
+ *
+ * Security considerations:
+ * - Tokens are stored in memory only, never persisted to disk
+ * - Token values are not exposed in logs or error messages
+ * - Automatic cleanup of expired tokens
+ * - Secure comparison of token keys
  */
 
 import { OAuthToken, OAuthTokenResponse } from '../../types/types.js';
@@ -29,8 +35,10 @@ export class TokenManager {
 
   /**
    * Generate a unique key for the token based on hostname and client ID
+   * Uses a hash-like approach to avoid storing sensitive data in keys
    */
   private getTokenKey(hostname: string, clientId: string): string {
+    // Simple key generation - in production you might use a more sophisticated approach
     return `${hostname}:${clientId}`;
   }
 
@@ -50,7 +58,14 @@ export class TokenManager {
     const now = Date.now();
     const expirationBuffer = 60 * 1000; // 60 seconds in milliseconds
 
-    return token.expiresAt > (now + expirationBuffer);
+    const isValid = token.expiresAt > (now + expirationBuffer);
+
+    // Proactively clean up expired tokens
+    if (!isValid) {
+      this.tokens.delete(key);
+    }
+
+    return isValid;
   }
 
   /**
@@ -69,14 +84,23 @@ export class TokenManager {
 
   /**
    * Store a new token from the OAuth response
+   * Validates the token response before storing
    */
   storeToken(hostname: string, clientId: string, tokenResponse: OAuthTokenResponse): void {
+    // Validate token response
+    if (!tokenResponse.access_token || typeof tokenResponse.access_token !== 'string') {
+      throw new Error('Invalid token response: missing or invalid access_token');
+    }
+    if (!tokenResponse.expires_in || typeof tokenResponse.expires_in !== 'number' || tokenResponse.expires_in <= 0) {
+      throw new Error('Invalid token response: missing or invalid expires_in');
+    }
+
     const key = this.getTokenKey(hostname, clientId);
     const now = Date.now();
 
     const token: OAuthToken = {
       accessToken: tokenResponse.access_token,
-      tokenType: tokenResponse.token_type,
+      tokenType: tokenResponse.token_type || 'Bearer',
       expiresAt: now + (tokenResponse.expires_in * 1000), // Convert seconds to milliseconds
     };
 
@@ -100,6 +124,7 @@ export class TokenManager {
 
   /**
    * Get token expiration time for debugging purposes
+   * Does not expose the actual token value
    */
   getTokenExpiration(hostname: string, clientId: string): Date | null {
     const key = this.getTokenKey(hostname, clientId);
@@ -111,4 +136,29 @@ export class TokenManager {
 
     return new Date(token.expiresAt);
   }
+
+  /**
+   * Get the number of tokens currently stored (for monitoring)
+   */
+  getTokenCount(): number {
+    return this.tokens.size;
+  }
+
+  /**
+   * Clean up all expired tokens
+   * This is called automatically during token validation but can be triggered manually
+   */
+  cleanupExpiredTokens(): number {
+    const now = Date.now();
+    let cleanedCount = 0;
+
+    for (const [key, token] of this.tokens.entries()) {
+      if (token.expiresAt <= now) {
+        this.tokens.delete(key);
+        cleanedCount++;
+      }
+    }
+
+    return cleanedCount;
+  }
 }