@lydt/geogebra-studio 0.0.0-stage → 0.4.0-rc.2

package/src/utils/logger.ts

@@ -0,0 +1,60 @@
+import winston from 'winston';
+
+interface LogInfo {
+  timestamp: string;
+  level: string;
+  message: string;
+  stack?: string;
+  [key: string]: unknown;
+}
+
+// Check if we're in MCP mode (stdio communication)
+// When piping input, process.stdin.isTTY is undefined, not false
+const isMcpMode = !process.stdin.isTTY;
+
+// Create logger instance
+const logger = winston.createLogger({
+  level: isMcpMode ? 'error' : (process.env['LOG_LEVEL'] || 'info'),
+  format: winston.format.combine(
+    winston.format.timestamp({
+      format: 'YYYY-MM-DD HH:mm:ss'
+    }),
+    winston.format.errors({ stack: true }),
+    winston.format.printf((info) => {
+      const { timestamp, level, message, stack, ...meta } = info as unknown as LogInfo;
+      let log = `${timestamp} [${level.toUpperCase()}]: ${message}`;
+      
+      if (Object.keys(meta).length > 0) {
+        log += ` ${JSON.stringify(meta)}`;
+      }
+      
+      if (stack) {
+        log += `\n${stack}`;
+      }
+      
+      return log;
+    })
+  ),
+  defaultMeta: { service: 'geogebra-mcp-server' },
+  transports: [
+    // Use stderr instead of stdout to avoid interfering with MCP JSON-RPC communication
+    new winston.transports.Console({
+      stderrLevels: ['error', 'warn', 'info', 'debug'],
+      format: winston.format.simple() // Remove colorization for MCP compatibility
+    })
+  ]
+});
+
+// Add file transport in production
+if (process.env['NODE_ENV'] === 'production') {
+  logger.add(new winston.transports.File({
+    filename: 'logs/error.log',
+    level: 'error'
+  }));
+  
+  logger.add(new winston.transports.File({
+    filename: 'logs/combined.log'
+  }));
+}
+
+export default logger; 

package/src/utils/performance/index.ts

@@ -0,0 +1,211 @@
+/**
+ * Performance Monitoring and Optimization System
+ * GEB-9: Performance Optimization: Response Time and Resource Management
+ */
+
+export interface PerformanceMetrics {
+  operationName: string;
+  startTime: number;
+  endTime: number;
+  duration: number;
+  success: boolean;
+  errorMessage?: string;
+  memoryUsage?: NodeJS.MemoryUsage;
+  metadata?: Record<string, any>;
+}
+
+export interface PerformanceThresholds {
+  [operationName: string]: {
+    warning: number;  // milliseconds
+    critical: number; // milliseconds
+  };
+}
+
+export class PerformanceMonitor {
+  private static instance: PerformanceMonitor;
+  private metrics: PerformanceMetrics[] = [];
+  private thresholds: PerformanceThresholds;
+  private maxMetrics: number = 1000; // Keep last 1000 metrics
+
+  // PRD requirements: <2 second response time
+  private defaultThresholds: PerformanceThresholds = {
+    'geogebra_eval_command': { warning: 1000, critical: 2000 },
+    'geogebra_create_point': { warning: 500, critical: 1000 },
+    'geogebra_create_line': { warning: 500, critical: 1000 },
+    'geogebra_export_png': { warning: 1500, critical: 2000 },
+    'geogebra_export_svg': { warning: 800, critical: 1500 },
+    'geogebra_instance_init': { warning: 8000, critical: 15000 },
+    'geogebra_clear_construction': { warning: 300, critical: 1000 },
+    'default': { warning: 1000, critical: 2000 }
+  };
+
+  private constructor() {
+    this.thresholds = { ...this.defaultThresholds };
+  }
+
+  static getInstance(): PerformanceMonitor {
+    if (!PerformanceMonitor.instance) {
+      PerformanceMonitor.instance = new PerformanceMonitor();
+    }
+    return PerformanceMonitor.instance;
+  }
+
+  /**
+   * Start timing an operation
+   */
+  startTiming(operationName: string, metadata?: Record<string, any>): (success?: boolean, errorMessage?: string) => PerformanceMetrics {
+    const startTime = performance.now();
+    const startMemory = process.memoryUsage();
+
+    return (success: boolean = true, errorMessage?: string) => {
+      const endTime = performance.now();
+      const endMemory = process.memoryUsage();
+      const duration = endTime - startTime;
+
+      const metric: PerformanceMetrics = {
+        operationName,
+        startTime,
+        endTime,
+        duration,
+        success,
+        ...(errorMessage && { errorMessage }),
+        memoryUsage: {
+          rss: endMemory.rss - startMemory.rss,
+          heapTotal: endMemory.heapTotal - startMemory.heapTotal,
+          heapUsed: endMemory.heapUsed - startMemory.heapUsed,
+          external: endMemory.external - startMemory.external,
+          arrayBuffers: endMemory.arrayBuffers - startMemory.arrayBuffers
+        },
+        ...(metadata && { metadata })
+      };
+
+      this.addMetric(metric);
+      this.checkThresholds(metric);
+      return metric;
+    };
+  }
+
+  /**
+   * Measure and record an async operation
+   */
+  async measureOperation<T>(
+    operationName: string,
+    operation: () => Promise<T>,
+    metadata?: Record<string, any>
+  ): Promise<T> {
+    const endTiming = this.startTiming(operationName, metadata);
+    
+    try {
+      const result = await operation();
+      endTiming(true);
+      return result;
+    } catch (error) {
+      endTiming(false, error instanceof Error ? error.message : String(error));
+      throw error;
+    }
+  }
+
+  /**
+   * Add a metric to the collection
+   */
+  private addMetric(metric: PerformanceMetrics): void {
+    this.metrics.push(metric);
+    
+    // Keep only the last maxMetrics entries
+    if (this.metrics.length > this.maxMetrics) {
+      this.metrics = this.metrics.slice(-this.maxMetrics);
+    }
+  }
+
+  /**
+   * Check if metric exceeds thresholds and log warnings
+   */
+  private checkThresholds(metric: PerformanceMetrics): void {
+    const threshold = this.thresholds[metric.operationName] || this.thresholds['default'];
+    
+    if (threshold && metric.duration > threshold.critical) {
+      console.error(`🚨 CRITICAL: ${metric.operationName} took ${metric.duration.toFixed(2)}ms (threshold: ${threshold.critical}ms)`);
+    } else if (threshold && metric.duration > threshold.warning) {
+      console.warn(`⚠️  WARNING: ${metric.operationName} took ${metric.duration.toFixed(2)}ms (threshold: ${threshold.warning}ms)`);
+    }
+  }
+
+  /**
+   * Get performance statistics for an operation
+   */
+  getStats(operationName?: string): {
+    count: number;
+    averageDuration: number;
+    medianDuration: number;
+    minDuration: number;
+    maxDuration: number;
+    successRate: number;
+    p95Duration: number;
+    p99Duration: number;
+  } {
+    const relevantMetrics = operationName 
+      ? this.metrics.filter(m => m.operationName === operationName)
+      : this.metrics;
+
+    if (relevantMetrics.length === 0) {
+      return {
+        count: 0,
+        averageDuration: 0,
+        medianDuration: 0,
+        minDuration: 0,
+        maxDuration: 0,
+        successRate: 0,
+        p95Duration: 0,
+        p99Duration: 0
+      };
+    }
+
+    const durations = relevantMetrics.map(m => m.duration).sort((a, b) => a - b);
+    const successCount = relevantMetrics.filter(m => m.success).length;
+
+    return {
+      count: relevantMetrics.length,
+      averageDuration: durations.reduce((sum, d) => sum + d, 0) / durations.length,
+      medianDuration:
+        durations.length % 2 === 0
+          ? ((durations[durations.length / 2 - 1] ?? 0) + (durations[durations.length / 2] ?? 0)) / 2
+          : durations[Math.floor(durations.length / 2)] ?? 0,
+      minDuration: durations[0] || 0,
+      maxDuration: durations[durations.length - 1] || 0,
+      successRate: successCount / relevantMetrics.length,
+      p95Duration: durations[Math.floor(durations.length * 0.95)] || 0,
+      p99Duration: durations[Math.floor(durations.length * 0.99)] || 0
+    };
+  }
+
+  /**
+   * Get all operation names with metrics
+   */
+  getOperationNames(): string[] {
+    return [...new Set(this.metrics.map(m => m.operationName))];
+  }
+
+  /**
+   * Clear all metrics
+   */
+  clearMetrics(): void {
+    this.metrics = [];
+  }
+
+  /**
+   * Export metrics for analysis
+   */
+  exportMetrics(): PerformanceMetrics[] {
+    return [...this.metrics];
+  }
+
+  /**
+   * Set custom thresholds
+   */
+  setThresholds(thresholds: Partial<PerformanceThresholds>): void {
+    Object.assign(this.thresholds, thresholds);
+  }
+}
+
+// Global instance
+export const performanceMonitor = PerformanceMonitor.getInstance(); 

package/src/utils/performance/instance-pool.ts

@@ -0,0 +1,323 @@
+/**
+ * Optimized GeoGebra Instance Pool Management
+ * GEB-9: Performance Optimization: Response Time and Resource Management
+ */
+
+import { GeoGebraInstance } from '../geogebra-instance';
+import { GeoGebraPoolConfig } from '../../types/geogebra';
+import logger from '../logger';
+import { performanceMonitor } from './index';
+
+// Check if we're in MCP mode (stdio communication)
+// When piping input, process.stdin.isTTY is undefined, not false
+const isMcpMode = !process.stdin.isTTY;
+
+export interface PooledInstance {
+  instance: GeoGebraInstance;
+  isActive: boolean;
+  lastUsed: Date;
+  createdAt: Date;
+  usageCount: number;
+}
+
+export class OptimizedInstancePool {
+  private static poolInstance: OptimizedInstancePool;
+  private instances: Map<string, PooledInstance> = new Map();
+  private config: GeoGebraPoolConfig;
+  private cleanupInterval?: NodeJS.Timeout | undefined;
+
+  private defaultConfig: GeoGebraPoolConfig = {
+    maxInstances: 3,        // Maximum concurrent instances
+    instanceTimeout: 300000, // 5 minutes
+    maxIdleTime: 600000,    // 10 minutes
+    headless: true,
+    browserArgs: [
+      '--no-sandbox',
+      '--disable-setuid-sandbox',
+      '--disable-dev-shm-usage',
+      '--disable-accelerated-2d-canvas',
+      '--no-first-run',
+      '--no-zygote',
+      '--disable-gpu',
+      '--memory-pressure-off',  // Reduce memory pressure
+      '--max_old_space_size=512' // Limit memory usage
+    ]
+  };
+
+  private constructor(config?: Partial<GeoGebraPoolConfig>) {
+    this.config = { ...this.defaultConfig, ...config };
+    this.startCleanupTimer();
+    
+    // Transport lifecycle owns graceful cleanup.
+    
+    if (!isMcpMode) {
+      logger.info('Optimized Instance Pool initialized', { config: this.config });
+    }
+  }
+
+  static getInstance(config?: Partial<GeoGebraPoolConfig>): OptimizedInstancePool {
+    if (!OptimizedInstancePool.poolInstance) {
+      OptimizedInstancePool.poolInstance = new OptimizedInstancePool(config);
+    }
+    return OptimizedInstancePool.poolInstance;
+  }
+
+  /**
+   * Get an available instance from the pool
+   */
+  async getInstance(): Promise<GeoGebraInstance> {
+    return performanceMonitor.measureOperation('instance_pool_get', async () => {
+      // Try to find an available instance
+      let availableInstance = this.findAvailableInstance();
+      
+      if (!availableInstance) {
+        // Create new instance if under limit
+        if (this.instances.size < this.config.maxInstances) {
+          availableInstance = await this.createNewInstance();
+        } else {
+          // Wait for an instance to become available or force cleanup
+          await this.forceCleanupOldest();
+          availableInstance = await this.createNewInstance();
+        }
+      }
+
+      // Mark as active and update usage stats
+      const pooled = this.instances.get(availableInstance.id)!;
+      pooled.isActive = true;
+      pooled.lastUsed = new Date();
+      pooled.usageCount++;
+
+      logger.debug(`Instance ${availableInstance.id} acquired from pool`, {
+        totalInstances: this.instances.size,
+        activeInstances: this.getActiveCount(),
+        usageCount: pooled.usageCount
+      });
+
+      return availableInstance;
+    });
+  }
+
+  /**
+   * Release an instance back to the pool
+   */
+  async releaseInstance(instance: GeoGebraInstance): Promise<void> {
+    return performanceMonitor.measureOperation('instance_pool_release', async () => {
+      const pooled = this.instances.get(instance.id);
+      if (pooled) {
+        pooled.isActive = false;
+        pooled.lastUsed = new Date();
+        
+        // Clear construction to reset state for next use
+        try {
+          await instance.newConstruction();
+        } catch (error) {
+          logger.warn(`Failed to clear construction on release: ${error}`);
+        }
+
+        logger.debug(`Instance ${instance.id} released to pool`, {
+          totalInstances: this.instances.size,
+          activeInstances: this.getActiveCount()
+        });
+      }
+    });
+  }
+
+  /**
+   * Find an available (non-active) instance
+   */
+  private findAvailableInstance(): GeoGebraInstance | null {
+    for (const [, pooled] of this.instances) {
+      if (!pooled.isActive) {
+        return pooled.instance;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Create a new instance and add to pool
+   */
+  private async createNewInstance(): Promise<GeoGebraInstance> {
+    return performanceMonitor.measureOperation('instance_pool_create', async () => {
+      const instance = new GeoGebraInstance({
+        appName: 'classic',
+        width: 800,
+        height: 600,
+        showMenuBar: false,
+        showToolBar: false,
+        showAlgebraInput: false
+      });
+
+      await instance.initialize(this.config.headless, this.config.browserArgs);
+      
+      const pooled: PooledInstance = {
+        instance,
+        isActive: false,
+        lastUsed: new Date(),
+        createdAt: new Date(),
+        usageCount: 0
+      };
+
+      this.instances.set(instance.id, pooled);
+      
+      logger.info(`New instance ${instance.id} created and added to pool`, {
+        totalInstances: this.instances.size
+      });
+
+      return instance;
+    });
+  }
+
+  /**
+   * Force cleanup of the oldest instance to make room
+   */
+  private async forceCleanupOldest(): Promise<void> {
+    let oldestId: string | null = null;
+    let oldestTime = Date.now();
+
+    // Find oldest inactive instance
+    for (const [id, pooled] of this.instances) {
+      if (!pooled.isActive && pooled.lastUsed.getTime() < oldestTime) {
+        oldestTime = pooled.lastUsed.getTime();
+        oldestId = id;
+      }
+    }
+
+    // If no inactive instance, find oldest active one
+    if (!oldestId) {
+      for (const [id, pooled] of this.instances) {
+        if (pooled.lastUsed.getTime() < oldestTime) {
+          oldestTime = pooled.lastUsed.getTime();
+          oldestId = id;
+        }
+      }
+    }
+
+    if (oldestId) {
+      await this.removeInstance(oldestId);
+      logger.info(`Forced cleanup of oldest instance ${oldestId} to make room`);
+    }
+  }
+
+  /**
+   * Remove and cleanup an instance
+   */
+  private async removeInstance(instanceId: string): Promise<void> {
+    const pooled = this.instances.get(instanceId);
+    if (pooled) {
+      try {
+        await pooled.instance.cleanup();
+      } catch (error) {
+        logger.error(`Error cleaning up instance ${instanceId}:`, error);
+      }
+      this.instances.delete(instanceId);
+    }
+  }
+
+  /**
+   * Start automatic cleanup timer
+   */
+  private startCleanupTimer(): void {
+    this.cleanupInterval = setInterval(() => {
+      this.performCleanup();
+    }, 60000); // Run cleanup every minute
+    this.cleanupInterval.unref();
+  }
+
+  /**
+   * Perform periodic cleanup of idle instances
+   */
+  private async performCleanup(): Promise<void> {
+    const now = Date.now();
+    const instancesToRemove: string[] = [];
+
+    for (const [id, pooled] of this.instances) {
+      const idleTime = now - pooled.lastUsed.getTime();
+      const isExpired = idleTime > this.config.maxIdleTime;
+      const isOld = (now - pooled.createdAt.getTime()) > this.config.instanceTimeout;
+      
+      if (!pooled.isActive && (isExpired || isOld)) {
+        instancesToRemove.push(id);
+      }
+    }
+
+    for (const id of instancesToRemove) {
+      await this.removeInstance(id);
+      logger.debug(`Cleaned up idle instance ${id}`);
+    }
+
+    if (instancesToRemove.length > 0) {
+      logger.info(`Cleanup completed: removed ${instancesToRemove.length} idle instances`);
+    }
+  }
+
+  /**
+   * Get count of active instances
+   */
+  private getActiveCount(): number {
+    return Array.from(this.instances.values()).filter(p => p.isActive).length;
+  }
+
+  /**
+   * Get pool statistics
+   */
+  getStats(): {
+    totalInstances: number;
+    activeInstances: number;
+    averageUsage: number;
+    oldestInstanceAge: number;
+    memoryEstimate: number; // MB
+  } {
+    const instances = Array.from(this.instances.values());
+    const now = Date.now();
+    
+    return {
+      totalInstances: instances.length,
+      activeInstances: this.getActiveCount(),
+      averageUsage: instances.reduce((sum, p) => sum + p.usageCount, 0) / instances.length || 0,
+      oldestInstanceAge: instances.length > 0 
+        ? Math.max(...instances.map(p => now - p.createdAt.getTime())) / 1000 
+        : 0,
+      memoryEstimate: instances.length * 75 // Approximate 75MB per instance
+    };
+  }
+
+  /**
+   * Cleanup all instances and stop timers
+   */
+  async cleanup(): Promise<void> {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = undefined;
+    }
+
+    const cleanupPromises = Array.from(this.instances.keys()).map(id => 
+      this.removeInstance(id)
+    );
+
+    await Promise.all(cleanupPromises);
+    
+    logger.info('Instance pool cleaned up completely');
+  }
+
+  /**
+   * Warm up the pool by pre-creating instances
+   */
+  async warmUp(count: number = 1): Promise<void> {
+    const warmUpPromises: Promise<void>[] = [];
+    
+    for (let i = 0; i < count && this.instances.size < this.config.maxInstances; i++) {
+      warmUpPromises.push(
+        this.createNewInstance().then(instance => 
+          this.releaseInstance(instance)
+        )
+      );
+    }
+
+    await Promise.all(warmUpPromises);
+    logger.info(`Pool warmed up with ${count} pre-created instances`);
+  }
+}
+
+// Global optimized pool instance
+export const optimizedInstancePool = OptimizedInstancePool.getInstance();