refactor: enhance initialization process in ProjectDevlogManager and TypeORMStorageProvider to prevent race conditions

Author: Marvin Zhang

packages/core/src/managers/devlog/project-devlog-manager.ts

@@ -39,28 +39,57 @@ export class ProjectDevlogManager {
 
   /**
    * Initialize the devlog manager
+   * Protects against race conditions during concurrent initialization
    */
   async initialize(): Promise<void> {
+    // If already initialized, return immediately
     if (this.initialized) {
       console.log('🔄 ProjectDevlogManager already initialized, skipping...');
       return;
     }
 
+    // If initialization is in progress, wait for it
+    if (this.initPromise) {
+      console.log('⏳ ProjectDevlogManager initialization in progress, waiting...');
+      return this.initPromise;
+    }
+
     console.log('🚀 Initializing ProjectDevlogManager...');
 
-    if (this.options.projectContext) {
-      console.log(`📂 Project context: ${this.options.projectContext.projectId}`);
-    } else {
-      console.log('📂 No project context configured');
+    // Create initialization promise to prevent race conditions
+    this.initPromise = this.performInitialization();
+
+    try {
+      await this.initPromise;
+    } catch (error) {
+      // Clear promise on failure so next call can retry
+      this.initPromise = null;
+      throw error;
     }
+  }
 
-    console.log(`💾 Storage type: ${this.options.storageConfig.type}`);
+  /**
+   * Internal method to perform the actual initialization
+   */
+  private async performInitialization(): Promise<void> {
+    try {
+      if (this.options.projectContext) {
+        console.log(`📂 Project context: ${this.options.projectContext.projectId}`);
+      } else {
+        console.log('📂 No project context configured');
+      }
 
-    this.storageProvider = await StorageProviderFactory.create(this.options.storageConfig);
-    await this.storageProvider.initialize();
+      console.log(`💾 Storage type: ${this.options.storageConfig.type}`);
 
-    this.initialized = true;
-    console.log('✅ ProjectDevlogManager initialized successfully');
+      this.storageProvider = await StorageProviderFactory.create(this.options.storageConfig);
+      await this.storageProvider.initialize();
+
+      this.initialized = true;
+      console.log('✅ ProjectDevlogManager initialized successfully');
+    } catch (error) {
+      console.error('❌ ProjectDevlogManager initialization failed:', error);
+      throw error;
+    }
   }
 
   /**

packages/core/src/storage/providers/typeorm-storage.ts

@@ -49,6 +49,9 @@ export class TypeORMStorageProvider implements StorageProvider {
   private chatDevlogLinkRepository?: Repository<ChatDevlogLinkEntity>;
   private options: TypeORMStorageOptions;
 
+  // Initialization race condition protection
+  private initializationPromise: Promise<void> | null = null;
+
   // Event subscription properties
   private eventCallbacks = new Set<(event: DevlogEvent) => void>();
   private isWatching = false;
@@ -59,9 +62,37 @@ export class TypeORMStorageProvider implements StorageProvider {
   }
 
   async initialize(): Promise<void> {
+    // If already initialized, return immediately
+    if (this.dataSource.isInitialized && this.repository) {
+      console.log('[TypeORMStorage] Already initialized, skipping...');
+      return;
+    }
+
+    // If initialization is in progress, wait for it
+    if (this.initializationPromise) {
+      console.log('[TypeORMStorage] Initialization in progress, waiting...');
+      return this.initializationPromise;
+    }
+
+    console.log('[TypeORMStorage] Starting new initialization...');
+
+    // Create initialization promise to prevent race conditions
+    this.initializationPromise = this.doInitialize();
+
+    try {
+      await this.initializationPromise;
+    } catch (error) {
+      // Clear the promise on failure so next call can retry
+      this.initializationPromise = null;
+      throw error;
+    }
+  }
+
+  private async doInitialize(): Promise<void> {
     try {
       // Check if already initialized to prevent "already connected" errors in development
       if (!this.dataSource.isInitialized) {
+        console.log(`[TypeORMStorage] Connecting to ${this.options.type} database...`);
         await this.dataSource.initialize();
         console.log('[TypeORMStorage] Connected to database successfully');
       } else {
@@ -84,7 +115,10 @@ export class TypeORMStorageProvider implements StorageProvider {
           // Don't fail initialization if chat tables already exist
         }
       }
+
+      console.log('[TypeORMStorage] Repositories initialized successfully');
     } catch (error) {
+      console.error('[TypeORMStorage] Initialization failed:', error);
       throw new Error(`Failed to initialize TypeORM storage: ${error}`);
     }
   }

packages/core/src/storage/storage-provider.ts

@@ -8,9 +8,42 @@ import { TypeORMStorageOptions } from './typeorm/typeorm-config.js';
 
 /**
  * Factory for creating storage providers based on configuration
+ * Implements singleton pattern to prevent race conditions and duplicate connections
  */
 export class StorageProviderFactory {
+  private static instanceCache = new Map<string, Promise<StorageProvider>>();
+
   static async create(config?: StorageConfig): Promise<StorageProvider> {
+    // Generate cache key based on configuration
+    const cacheKey = StorageProviderFactory.generateCacheKey(config);
+
+    // Return existing instance if available
+    if (StorageProviderFactory.instanceCache.has(cacheKey)) {
+      console.log(`📦 StorageProviderFactory: Returning cached ${config?.type} provider`);
+      return StorageProviderFactory.instanceCache.get(cacheKey)!;
+    }
+
+    console.log(`🚀 StorageProviderFactory: Creating new ${config?.type} provider`);
+
+    // Create initialization promise to prevent race conditions
+    const initPromise = StorageProviderFactory.createProvider(config);
+
+    // Cache the promise immediately to prevent concurrent creation
+    StorageProviderFactory.instanceCache.set(cacheKey, initPromise);
+
+    try {
+      const provider = await initPromise;
+      console.log(`✅ StorageProviderFactory: ${config?.type} provider created and initialized`);
+      return provider;
+    } catch (error) {
+      // Remove failed initialization from cache so it can be retried
+      StorageProviderFactory.instanceCache.delete(cacheKey);
+      console.error(`❌ StorageProviderFactory: Failed to create ${config?.type} provider:`, error);
+      throw error;
+    }
+  }
+
+  private static async createProvider(config?: StorageConfig): Promise<StorageProvider> {
     // Handle storage types (GitHub is now an integration, not storage)
     switch (config?.type) {
       case 'sqlite':
@@ -78,4 +111,52 @@ export class StorageProviderFactory {
         return new JsonStorageProvider(config?.json || {});
     }
   }
+
+  /**
+   * Generate cache key based on storage configuration
+   */
+  private static generateCacheKey(config?: StorageConfig): string {
+    if (!config) {
+      return 'json:default';
+    }
+
+    switch (config.type) {
+      case 'sqlite':
+        return `sqlite:${config.connectionString || '.devlog/devlog.sqlite'}`;
+
+      case 'postgres':
+        return `postgres:${config.connectionString || 'default'}`;
+
+      case 'mysql':
+        if (config.connectionString) {
+          return `mysql:${config.connectionString}`;
+        }
+        const host = config.options?.host || 'localhost';
+        const port = config.options?.port || 3306;
+        const database = config.options?.database || 'default';
+        return `mysql:${host}:${port}:${database}`;
+
+      case 'json':
+      default:
+        return 'json:default';
+    }
+  }
+
+  /**
+   * Clear the instance cache (useful for testing or configuration changes)
+   */
+  static clearCache(): void {
+    console.log('🧹 StorageProviderFactory: Clearing instance cache');
+    StorageProviderFactory.instanceCache.clear();
+  }
+
+  /**
+   * Get cache statistics for debugging
+   */
+  static getCacheStats(): { size: number; keys: string[] } {
+    return {
+      size: StorageProviderFactory.instanceCache.size,
+      keys: Array.from(StorageProviderFactory.instanceCache.keys()),
+    };
+  }
 }