@dizzlkheinz/ynab-mcpb 0.12.1

package/src/server/deltaCache.ts

@@ -0,0 +1,341 @@
+import { CacheManager } from './cacheManager.js';
+import globalRequestLogger from './requestLogger.js';
+import { ServerKnowledgeStore } from './serverKnowledgeStore.js';
+
+export interface Logger {
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+}
+
+const LARGE_KNOWLEDGE_GAP_THRESHOLD = 100;
+
+const requestLoggerAdapter: Logger = {
+  info(message, meta) {
+    globalRequestLogger.logSuccess('delta-cache', message, meta ? { ...meta } : {});
+  },
+  warn(message, meta) {
+    const parameters: Record<string, unknown> = {
+      ...(meta ? { ...meta } : {}),
+      severity: 'warn',
+    };
+    globalRequestLogger.logSuccess('delta-cache', message, parameters);
+  },
+  error(message, meta) {
+    const parameters: Record<string, unknown> = meta ? { ...meta } : {};
+    const errorField = parameters['error'];
+    const errorDetail = typeof errorField === 'string' ? errorField : message;
+    globalRequestLogger.logError('delta-cache', message, parameters, errorDetail);
+  },
+};
+
+/**
+ * Options for merge operations
+ */
+export interface MergeOptions {
+  /** Whether to preserve deleted entities (default: false) */
+  preserveDeleted?: boolean;
+  /**
+   * Custom equality function for deduplication.
+   *
+   * NOTE: The built-in merge functions (mergeFlatEntities, mergeCategories, mergeTransactions)
+   * ignore this field and use ID-based equality (`entity.id`). This field is available for
+   * caller-supplied custom merge functions that need non-ID-based equality semantics.
+   *
+   * @example
+   * // Custom merge function using equalityFn:
+   * const customMerge: MergeFn<MyEntity> = (snapshot, delta, options) => {
+   *   const equals = options?.equalityFn || ((a, b) => a.id === b.id);
+   *   // Use equals() for custom deduplication logic
+   * };
+   */
+  equalityFn?: (a: unknown, b: unknown) => boolean;
+}
+
+export type MergeFn<T> = (snapshot: T[], delta: T[], options?: MergeOptions) => T[];
+
+export interface DeltaFetchResult<T> {
+  data: T[];
+  wasCached: boolean;
+  usedDelta: boolean;
+  serverKnowledge: number;
+}
+
+export interface DeltaCacheEntry<T> {
+  snapshot: T[];
+  serverKnowledge: number;
+  timestamp: number;
+  ttl: number;
+  staleWhileRevalidate?: number;
+}
+
+export interface DeltaCacheStats {
+  deltaHits: number;
+  deltaMisses: number;
+  mergeOperations: number;
+  knowledgeGapEvents: number;
+}
+
+type DeltaFetcher<T> = (lastKnowledge?: number) => Promise<{ data: T[]; serverKnowledge: number }>;
+
+/**
+ * DeltaCache coordinates cache entries with server knowledge tracking to issue delta-aware requests.
+ * The feature is gated by YNAB_MCP_ENABLE_DELTA for safe rollouts.
+ */
+export class DeltaCache {
+  private deltaHits = 0;
+  private deltaMisses = 0;
+  private mergeOperations = 0;
+  private knowledgeGapEvents = 0;
+
+  constructor(
+    private readonly cacheManager: CacheManager,
+    private readonly knowledgeStore: ServerKnowledgeStore,
+    private readonly logger: Logger = requestLoggerAdapter,
+  ) {}
+
+  /**
+   * Fetch data with optional delta semantics using cached snapshots and merge functions.
+   *
+   * @param options.ttl - Required TTL in milliseconds. Callers must explicitly specify the appropriate
+   *                      resource-specific TTL (e.g., CACHE_TTLS.ACCOUNTS, CACHE_TTLS.CATEGORIES, etc.)
+   *                      to ensure each resource type uses correct cache expiration.
+   * @param options.staleWhileRevalidate - Optional stale-while-revalidate window in milliseconds.
+   *                                        Allows serving stale cache entries while refreshing in background.
+   */
+  async fetchWithDelta<T extends { deleted?: boolean }>(
+    cacheKey: string,
+    budgetId: string,
+    fetcher: DeltaFetcher<T>,
+    merger: MergeFn<T>,
+    options: {
+      ttl: number;
+      forceFullRefresh?: boolean;
+      mergeOptions?: MergeOptions;
+      staleWhileRevalidate?: number;
+    },
+  ): Promise<DeltaFetchResult<T>> {
+    const effectiveTtl = this.assertFiniteTtl('fetchWithDelta', cacheKey, options.ttl);
+
+    if (!this.isDeltaEnabled()) {
+      return this.fetchWithoutDelta(cacheKey, budgetId, fetcher, options);
+    }
+
+    // Always check cache, even with forceFullRefresh (which only disables delta merging)
+    const cachedEntry = this.cacheManager.get<DeltaCacheEntry<T>>(cacheKey);
+
+    // If forceFullRefresh is true but we have a fresh cache entry, return it
+    if (options.forceFullRefresh && cachedEntry) {
+      const age = Date.now() - cachedEntry.timestamp;
+      const isStale = age > cachedEntry.ttl;
+      if (!isStale) {
+        return {
+          data: cachedEntry.snapshot,
+          wasCached: true,
+          usedDelta: false,
+          serverKnowledge: cachedEntry.serverKnowledge,
+        };
+      }
+    }
+
+    const lastKnowledge = options.forceFullRefresh ? undefined : this.knowledgeStore.get(cacheKey);
+    const canUseDelta = Boolean(
+      !options.forceFullRefresh && cachedEntry && lastKnowledge !== undefined,
+    );
+    const requestedKnowledge = canUseDelta ? lastKnowledge : undefined;
+
+    let response = await fetcher(requestedKnowledge);
+    const knowledgeGap =
+      requestedKnowledge !== undefined ? response.serverKnowledge - requestedKnowledge : 0;
+
+    let forcedFullRefreshDueToGap = false;
+
+    if (knowledgeGap > LARGE_KNOWLEDGE_GAP_THRESHOLD) {
+      this.logger.warn('delta-cache.knowledge-gap', {
+        budgetId,
+        cacheKey,
+        lastKnowledge: requestedKnowledge,
+        serverKnowledge: response.serverKnowledge,
+        gap: knowledgeGap,
+        threshold: LARGE_KNOWLEDGE_GAP_THRESHOLD,
+        action: 'full-refresh',
+        recommendation: 'Consider forcing a full refresh to resync cache.',
+      });
+      forcedFullRefreshDueToGap = true;
+      this.knowledgeGapEvents++;
+      response = await fetcher(undefined);
+    }
+
+    const receivedDelta =
+      !forcedFullRefreshDueToGap &&
+      requestedKnowledge !== undefined &&
+      response.serverKnowledge > requestedKnowledge;
+
+    let finalSnapshot: T[];
+    let usedDelta = false;
+
+    if (receivedDelta && cachedEntry) {
+      this.mergeOperations++;
+      finalSnapshot = merger(cachedEntry.snapshot, response.data, options.mergeOptions);
+      usedDelta = true;
+    } else if (cachedEntry && requestedKnowledge !== undefined && !forcedFullRefreshDueToGap) {
+      // No changes were reported, so reuse the cached snapshot
+      finalSnapshot = cachedEntry.snapshot;
+    } else {
+      finalSnapshot = this.filterDeleted(response.data);
+    }
+
+    const cacheEntry: DeltaCacheEntry<T> = {
+      snapshot: finalSnapshot,
+      serverKnowledge: response.serverKnowledge,
+      timestamp: Date.now(),
+      ttl: effectiveTtl,
+    };
+
+    if (options.staleWhileRevalidate !== undefined) {
+      cacheEntry.staleWhileRevalidate = options.staleWhileRevalidate;
+    }
+
+    const cacheOptions: { ttl: number; staleWhileRevalidate?: number } = {
+      ttl: effectiveTtl,
+    };
+    if (options.staleWhileRevalidate !== undefined) {
+      cacheOptions.staleWhileRevalidate = options.staleWhileRevalidate;
+    }
+
+    this.cacheManager.set(cacheKey, cacheEntry, cacheOptions);
+    this.knowledgeStore.update(cacheKey, response.serverKnowledge);
+
+    if (canUseDelta) {
+      this.deltaHits++;
+    } else {
+      this.deltaMisses++;
+    }
+
+    return {
+      data: finalSnapshot,
+      wasCached: Boolean(cachedEntry),
+      usedDelta,
+      serverKnowledge: response.serverKnowledge,
+    };
+  }
+
+  getStats(): DeltaCacheStats {
+    return {
+      deltaHits: this.deltaHits,
+      deltaMisses: this.deltaMisses,
+      mergeOperations: this.mergeOperations,
+      knowledgeGapEvents: this.knowledgeGapEvents,
+    };
+  }
+
+  /**
+   * Invalidate cached entries for a budget, optionally scoped to a resource type.
+   * Does not reset server knowledge to allow graceful follow-up delta requests.
+   */
+  invalidate(budgetId: string, resourceType?: string): void {
+    if (!budgetId) {
+      return;
+    }
+
+    if (resourceType) {
+      const prefix = `${resourceType}:list:${budgetId}`;
+      this.cacheManager.deleteByPrefix(prefix);
+    } else {
+      this.cacheManager.deleteByBudgetId(budgetId);
+    }
+  }
+
+  /**
+   * Force a full refresh by invalidating caches and resetting knowledge entries.
+   */
+  forceFullRefresh(budgetId?: string, resourceType?: string): void {
+    if (budgetId) {
+      this.invalidate(budgetId, resourceType);
+    } else {
+      this.cacheManager.clear();
+    }
+
+    if (resourceType && budgetId) {
+      this.knowledgeStore.reset(`${resourceType}:list:${budgetId}`);
+    } else if (budgetId) {
+      this.knowledgeStore.resetByBudgetId(budgetId);
+    } else {
+      this.knowledgeStore.reset();
+    }
+  }
+
+  private async fetchWithoutDelta<T extends { deleted?: boolean }>(
+    cacheKey: string,
+    _budgetId: string,
+    fetcher: DeltaFetcher<T>,
+    options: { ttl: number; forceFullRefresh?: boolean; staleWhileRevalidate?: number },
+  ): Promise<DeltaFetchResult<T>> {
+    const effectiveTtl = this.assertFiniteTtl('fetchWithoutDelta', cacheKey, options.ttl);
+
+    // Always check cache, even with forceFullRefresh (which only disables delta merging)
+    const cachedEntry = this.cacheManager.get<DeltaCacheEntry<T>>(cacheKey);
+
+    // If we have a fresh cache entry, return it
+    if (cachedEntry) {
+      const age = Date.now() - cachedEntry.timestamp;
+      const isStale = age > cachedEntry.ttl;
+      if (!isStale || !options.forceFullRefresh) {
+        return {
+          data: cachedEntry.snapshot,
+          wasCached: true,
+          usedDelta: false,
+          serverKnowledge: cachedEntry.serverKnowledge,
+        };
+      }
+    }
+
+    const response = await fetcher(undefined);
+    const cleanedData = this.filterDeleted(response.data);
+    const cacheEntry: DeltaCacheEntry<T> = {
+      snapshot: cleanedData,
+      serverKnowledge: response.serverKnowledge,
+      timestamp: Date.now(),
+      ttl: effectiveTtl,
+    };
+
+    if (options.staleWhileRevalidate !== undefined) {
+      cacheEntry.staleWhileRevalidate = options.staleWhileRevalidate;
+    }
+
+    const cacheOptions: { ttl: number; staleWhileRevalidate?: number } = {
+      ttl: effectiveTtl,
+    };
+    if (options.staleWhileRevalidate !== undefined) {
+      cacheOptions.staleWhileRevalidate = options.staleWhileRevalidate;
+    }
+
+    this.cacheManager.set(cacheKey, cacheEntry, cacheOptions);
+    this.knowledgeStore.update(cacheKey, response.serverKnowledge);
+
+    return {
+      data: cleanedData,
+      wasCached: false,
+      usedDelta: false,
+      serverKnowledge: response.serverKnowledge,
+    };
+  }
+
+  private filterDeleted<T extends { deleted?: boolean }>(items: T[]): T[] {
+    return items.filter((item) => !item.deleted);
+  }
+
+  private assertFiniteTtl(methodName: string, cacheKey: string, ttl: number): number {
+    if (!Number.isFinite(ttl)) {
+      throw new Error(
+        `DeltaCache.${methodName} requires a finite ttl for cache key "${cacheKey}". Received: ${String(ttl)}.`,
+      );
+    }
+
+    return ttl;
+  }
+
+  private isDeltaEnabled(): boolean {
+    return process.env['YNAB_MCP_ENABLE_DELTA'] === 'true';
+  }
+}

package/src/server/diagnostics.ts

@@ -0,0 +1,338 @@
+/**
+ * Diagnostics module for YNAB MCP Server
+ *
+ * Handles comprehensive system diagnostics collection.
+ * Extracted from YNABMCPServer to provide focused, testable diagnostics management.
+ */
+
+import type { CacheManager } from './cacheManager.js';
+import type { ServerKnowledgeStore } from './serverKnowledgeStore.js';
+import type { DeltaCache } from './deltaCache.js';
+
+/**
+ * Security stats provider interface
+ */
+export interface SecurityStatsProvider {
+  getSecurityStats(): unknown;
+}
+
+/**
+ * Response formatter interface to avoid direct dependency on concrete implementation
+ */
+interface ResponseFormatter {
+  format(data: unknown): string;
+}
+
+/**
+ * Diagnostic options for configuring what diagnostics to include
+ */
+export interface DiagnosticOptions {
+  include_server?: boolean;
+  include_memory?: boolean;
+  include_environment?: boolean;
+  include_security?: boolean;
+  include_cache?: boolean;
+  include_delta?: boolean;
+}
+
+/**
+ * Diagnostic data structure
+ */
+export interface DiagnosticData {
+  timestamp: string;
+  server?: {
+    name: string;
+    version: string;
+    node_version: string;
+    platform: string;
+    arch: string;
+    pid: number;
+    uptime_ms: number;
+    uptime_readable: string;
+    env: {
+      node_env: string;
+      minify_output: string;
+    };
+  };
+  memory?: {
+    rss_mb: number;
+    heap_used_mb: number;
+    heap_total_mb: number;
+    external_mb: number;
+    array_buffers_mb: number;
+    description: {
+      rss: string;
+      heap_used: string;
+      heap_total: string;
+      external: string;
+      array_buffers: string;
+    };
+  };
+  environment?: {
+    token_present: boolean;
+    token_length: number;
+    token_preview: string | null;
+    ynab_env_keys_present: string[];
+    working_directory: string;
+  };
+  security?: unknown;
+  cache?: {
+    entries: number;
+    estimated_size_kb: number;
+    keys: string[];
+    hits?: number;
+    misses?: number;
+    evictions?: number;
+    lastCleanup?: string | null;
+    maxEntries?: number;
+    hitRate?: string;
+    performance_summary?: string;
+  };
+}
+
+/**
+ * Injectable dependencies for diagnostic manager
+ */
+export interface DiagnosticDependencies {
+  securityMiddleware: SecurityStatsProvider;
+  cacheManager: CacheManager;
+  responseFormatter: ResponseFormatter;
+  serverVersion: string;
+  serverKnowledgeStore?: ServerKnowledgeStore;
+  deltaCache?: DeltaCache;
+}
+
+/**
+ * Formats a duration given in milliseconds into a concise human-readable uptime string.
+ *
+ * @param ms - Duration in milliseconds
+ * @returns A string such as "1d 2h 3m 4s", "2h 3m 4s", "3m 4s", or "45s" depending on the magnitude
+ */
+export function formatUptime(ms: number): string {
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (days > 0) {
+    return `${days}d ${hours % 24}h ${minutes % 60}m ${seconds % 60}s`;
+  } else if (hours > 0) {
+    return `${hours}h ${minutes % 60}m ${seconds % 60}s`;
+  } else if (minutes > 0) {
+    return `${minutes}m ${seconds % 60}s`;
+  } else {
+    return `${seconds}s`;
+  }
+}
+
+/**
+ * Convert a byte count to megabytes with two-decimal precision.
+ *
+ * @param bytes - The number of bytes to convert
+ * @returns The size in megabytes rounded to two decimal places
+ */
+export function formatBytes(bytes: number): number {
+  return Math.round((bytes / 1024 / 1024) * 100) / 100;
+}
+
+/**
+ * Produce a masked preview of an access token for safe display.
+ *
+ * The masking rules:
+ * - If `token` is falsy, returns `null`.
+ * - If `token` length is less than 8, returns the first character followed by `***`.
+ * - Otherwise, returns the first four characters, `...`, and the last four characters.
+ * - If the token contains a trailing hyphen segment within 6 characters of the end, the trailing segment (including the hyphen) is used as the last part.
+ *
+ * @param token - The token to mask
+ * @returns The masked token preview, or `null` if `token` is falsy
+ */
+export function maskToken(token: string | undefined): string | null {
+  if (!token) return null;
+
+  if (token.length < 8) {
+    return `${token.slice(0, 1)}***`;
+  }
+
+  const firstPart = token.slice(0, 4);
+  let lastPart = token.slice(-4);
+
+  const trailingHyphenIndex = token.lastIndexOf('-');
+  if (trailingHyphenIndex !== -1 && token.length - trailingHyphenIndex <= 6) {
+    lastPart = token.slice(trailingHyphenIndex);
+  }
+
+  return `${firstPart}...${lastPart}`;
+}
+
+/**
+ * DiagnosticManager class that handles diagnostic data collection
+ */
+export class DiagnosticManager {
+  private dependencies: DiagnosticDependencies;
+
+  constructor(dependencies: DiagnosticDependencies) {
+    this.dependencies = dependencies;
+  }
+
+  /**
+   * Collects comprehensive diagnostic information
+   */
+  async collectDiagnostics(options: DiagnosticOptions): Promise<{
+    content: { type: 'text'; text: string }[];
+  }> {
+    const diagnostics: Record<string, unknown> = {
+      timestamp: new Date().toISOString(),
+    };
+
+    if (options.include_server) {
+      const uptimeMs = Math.round(process.uptime() * 1000);
+      diagnostics['server'] = {
+        name: 'ynab-mcp-server',
+        version: this.dependencies.serverVersion,
+        node_version: process.version,
+        platform: process.platform,
+        arch: process.arch,
+        pid: process.pid,
+        uptime_ms: uptimeMs,
+        uptime_readable: formatUptime(uptimeMs),
+        env: {
+          node_env: process.env['NODE_ENV'] || 'development',
+          minify_output: process.env['YNAB_MCP_MINIFY_OUTPUT'] ?? 'true',
+        },
+      };
+    }
+
+    if (options.include_memory) {
+      const memUsage = process.memoryUsage();
+      diagnostics['memory'] = {
+        rss_mb: formatBytes(memUsage.rss),
+        heap_used_mb: formatBytes(memUsage.heapUsed),
+        heap_total_mb: formatBytes(memUsage.heapTotal),
+        external_mb: formatBytes(memUsage.external),
+        array_buffers_mb: formatBytes(memUsage.arrayBuffers ?? 0),
+        description: {
+          rss: 'Resident Set Size - total memory allocated for the process',
+          heap_used: 'Used heap memory (objects, closures, etc.)',
+          heap_total: 'Total heap memory allocated',
+          external: 'Memory used by C++ objects bound to JavaScript objects',
+          array_buffers: 'Memory allocated for ArrayBuffer and SharedArrayBuffer',
+        },
+      };
+    }
+
+    if (options.include_environment) {
+      const token = process.env['YNAB_ACCESS_TOKEN'];
+      const envKeys = Object.keys(process.env ?? {});
+      const ynabEnvKeys = envKeys.filter((key) => key.toUpperCase().includes('YNAB'));
+      const rawTokenLength = token?.length ?? 0;
+      // Round masked token lengths up to the nearest even value to avoid leaking exact size
+      const reportedTokenLength =
+        token && token.length >= 8 ? rawTokenLength + (rawTokenLength % 2) : rawTokenLength;
+
+      diagnostics['environment'] = {
+        token_present: !!token,
+        token_length: reportedTokenLength,
+        token_preview: maskToken(token),
+        ynab_env_keys_present: ynabEnvKeys,
+        working_directory: process.cwd(),
+      };
+    }
+
+    if (options.include_security) {
+      diagnostics['security'] = this.dependencies.securityMiddleware.getSecurityStats();
+    }
+
+    if (options.include_cache) {
+      const cacheStats = this.dependencies.cacheManager.getStats();
+      const estimateCacheSize = () => {
+        try {
+          // Use lightweight metadata instead of full entry data for size estimation
+          const metadata = this.dependencies.cacheManager.getCacheMetadata();
+          const serialized = JSON.stringify(metadata);
+          return Math.round(Buffer.byteLength(serialized, 'utf8') / 1024);
+        } catch {
+          return 0;
+        }
+      };
+
+      // Build performance summary
+      const performanceParts = [];
+      if ('hitRate' in cacheStats) {
+        const hitRatePercent = (cacheStats.hitRate * 100).toFixed(1);
+        performanceParts.push(
+          `Hit rate: ${hitRatePercent}% (${cacheStats.hits} hits, ${cacheStats.misses} misses)`,
+        );
+      }
+      if ('evictions' in cacheStats && cacheStats.evictions > 0) {
+        performanceParts.push(`LRU evictions: ${cacheStats.evictions}`);
+      }
+      if ('lastCleanup' in cacheStats && cacheStats.lastCleanup) {
+        const lastCleanupDate = new Date(cacheStats.lastCleanup);
+        const minutesAgo = Math.round((Date.now() - lastCleanupDate.getTime()) / (60 * 1000));
+        performanceParts.push(`Last cleanup: ${minutesAgo} minutes ago`);
+      }
+
+      const cacheData: {
+        entries: number;
+        estimated_size_kb: number;
+        keys: string[];
+        hits?: number;
+        misses?: number;
+        evictions?: number;
+        lastCleanup?: string | null;
+        maxEntries?: number;
+        hitRate?: string;
+        performance_summary?: string;
+      } = {
+        entries: cacheStats.size,
+        estimated_size_kb: estimateCacheSize(),
+        keys: cacheStats.keys,
+      };
+
+      // Add enhanced metrics if available
+      if ('hits' in cacheStats) {
+        cacheData.hits = cacheStats.hits;
+        cacheData.misses = cacheStats.misses;
+        cacheData.evictions = cacheStats.evictions;
+        cacheData.lastCleanup = cacheStats.lastCleanup
+          ? new Date(cacheStats.lastCleanup).toISOString()
+          : null;
+        cacheData.maxEntries = cacheStats.maxEntries;
+        cacheData.hitRate = `${(cacheStats.hitRate * 100).toFixed(2)}%`;
+
+        if (performanceParts.length > 0) {
+          cacheData.performance_summary = performanceParts.join(', ');
+        }
+      }
+
+      diagnostics['cache'] = cacheData;
+    }
+
+    if (
+      options.include_delta === true &&
+      this.dependencies.serverKnowledgeStore &&
+      this.dependencies.deltaCache
+    ) {
+      const knowledgeStats = this.dependencies.serverKnowledgeStore.getStats();
+      const deltaStats = this.dependencies.deltaCache.getStats();
+      const totalDeltaRequests = deltaStats.deltaHits + deltaStats.deltaMisses;
+      const deltaHitRate = totalDeltaRequests > 0 ? deltaStats.deltaHits / totalDeltaRequests : 0;
+      diagnostics['delta'] = {
+        enabled: process.env['YNAB_MCP_ENABLE_DELTA'] === 'true',
+        knowledge_entries: Object.keys(knowledgeStats.entries).length, // Canonical count from entries
+        knowledge_stats: knowledgeStats.entries,
+        feature_flag: process.env['YNAB_MCP_ENABLE_DELTA'] ?? 'false',
+        delta_hits: deltaStats.deltaHits,
+        delta_misses: deltaStats.deltaMisses,
+        delta_hit_rate: Number(deltaHitRate.toFixed(4)),
+        merge_operations: deltaStats.mergeOperations,
+        knowledge_gap_events: deltaStats.knowledgeGapEvents,
+      };
+    }
+
+    return {
+      content: [{ type: 'text', text: this.dependencies.responseFormatter.format(diagnostics) }],
+    };
+  }
+}