fss-link 1.0.51 → 1.0.53

package/dist/src/config/database.js

@@ -12,6 +12,10 @@ import { getDatabasePool } from './databasePool.js';
 import { MigrationManager } from './databaseMigrations.js';
 import { DatabaseBackupManager } from './databaseBackup.js';
 import { QueryOptimizer } from './queryOptimizer.js';
+import { DatabaseMetricsCollector } from './databaseMetrics.js';
+import { DatabaseHealthMonitor } from './databaseHealthMonitor.js';
+import { DatabaseSchemaValidator } from './databaseSchemaValidator.js';
+import { safeQueryFirst, safeQuery, safeExec, safeTransaction, getLastInsertId } from './database-utils.js';
 /**
  * FSS Link Database Manager
  * Handles all persistent state for model configurations and user preferences
@@ -27,6 +31,9 @@ export class FSSLinkDatabase {
     migrationManager;
     backupManager;
     queryOptimizer;
+    metricsCollector;
+    healthMonitor;
+    schemaValidator;
     constructor() {
         // Ensure FSS Link settings directory exists
         if (!fs.existsSync(USER_SETTINGS_DIR)) {
@@ -38,6 +45,9 @@ export class FSSLinkDatabase {
         this.migrationManager = new MigrationManager();
         this.backupManager = new DatabaseBackupManager();
         this.queryOptimizer = new QueryOptimizer();
+        this.metricsCollector = new DatabaseMetricsCollector();
+        this.healthMonitor = new DatabaseHealthMonitor();
+        this.schemaValidator = new DatabaseSchemaValidator();
     }
     /**
      * Derive encryption key from machine-specific data
@@ -55,7 +65,7 @@ export class FSSLinkDatabase {
         if (!apiKey)
             return '';
         const iv = crypto.randomBytes(16);
-        const cipher = crypto.createCipher('aes-256-cbc', this.encryptionKey);
+        const cipher = crypto.createCipheriv('aes-256-cbc', this.encryptionKey, iv);
         let encrypted = cipher.update(apiKey, 'utf8', 'hex');
         encrypted += cipher.final('hex');
         return `enc:${iv.toString('hex')}:${encrypted}`;
@@ -71,8 +81,9 @@ export class FSSLinkDatabase {
             const parts = encryptedData.substring(4).split(':'); // Remove 'enc:' prefix
             if (parts.length !== 2)
                 return encryptedData;
-            const [_ivHex, encrypted] = parts;
-            const decipher = crypto.createDecipher('aes-256-cbc', this.encryptionKey);
+            const [ivHex, encrypted] = parts;
+            const iv = Buffer.from(ivHex, 'hex');
+            const decipher = crypto.createDecipheriv('aes-256-cbc', this.encryptionKey, iv);
             let decrypted = decipher.update(encrypted, 'hex', 'utf8');
             decrypted += decipher.final('utf8');
             return decrypted;
@@ -88,35 +99,67 @@ export class FSSLinkDatabase {
     async initialize() {
         if (this.initialized)
             return;
-        // Initialize the connection pool
-        await this.pool.initialize();
-        // Use a connection from the pool to run migrations and initialize schema
-        await this.pool.withConnection(async (db) => {
-            this.db = db; // Keep reference for compatibility
-            // Create auto backup before migrations if database exists
-            const needsMigration = this.migrationManager.needsMigration(db);
-            if (needsMigration && fs.existsSync(this.dbPath)) {
-                try {
-                    console.log('Creating backup before migration...');
-                    await this.backupManager.createAutoBackup(db);
+        debugLog('Starting FSS Link database initialization...');
+        try {
+            // Initialize the connection pool
+            debugLog('Initializing database connection pool...');
+            await this.pool.initialize();
+            debugLog('Database connection pool initialized successfully');
+            // Use a connection from the pool to run migrations and initialize schema
+            await this.pool.withConnection(async (db) => {
+                this.db = db; // Keep reference for compatibility
+                debugLog('Database connection acquired, checking migration status...');
+                // Create auto backup before migrations if database exists
+                const needsMigration = this.migrationManager.needsMigration(db);
+                debugLog(`Migration needed: ${needsMigration}`);
+                if (needsMigration && fs.existsSync(this.dbPath)) {
+                    try {
+                        console.log('Creating backup before migration...');
+                        await this.backupManager.createAutoBackup(db);
+                        console.log('Pre-migration backup created successfully');
+                    }
+                    catch (error) {
+                        console.warn('Failed to create pre-migration backup:', error);
+                    }
                 }
-                catch (error) {
-                    console.warn('Failed to create pre-migration backup:', error);
+                // Run database migrations if needed
+                if (needsMigration) {
+                    debugLog('Running database migrations...');
+                    await this.migrationManager.migrate(db);
+                    debugLog('Database migrations completed successfully');
                 }
-            }
-            // Run database migrations if needed
-            if (needsMigration) {
-                console.log('Running database migrations...');
-                await this.migrationManager.migrate(db);
-            }
-            // Validate schema integrity
-            if (!this.migrationManager.validateSchema(db)) {
-                throw new Error('Database schema validation failed');
-            }
-            // Run legacy schema initialization for any missed items
-            await this.initializeSchema();
-        });
-        this.initialized = true;
+                else {
+                    debugLog('Database is up to date, no migrations needed');
+                }
+                // Validate schema integrity
+                debugLog('Validating database schema...');
+                if (!this.migrationManager.validateSchema(db)) {
+                    throw new Error('Database schema validation failed');
+                }
+                debugLog('Database schema validation passed');
+                // Run legacy schema initialization for any missed items
+                debugLog('Running legacy schema initialization...');
+                await this.initializeSchema();
+                debugLog('Legacy schema initialization completed');
+                // Final verification that critical tables exist
+                debugLog('Performing final table existence check...');
+                const criticalTables = ['model_configs', 'provider_usage_stats', 'user_preferences'];
+                for (const tableName of criticalTables) {
+                    const tableCheck = db.exec(`SELECT name FROM sqlite_master WHERE type='table' AND name='${tableName}'`);
+                    if (tableCheck.length === 0) {
+                        throw new Error(`Critical table '${tableName}' missing after initialization`);
+                    }
+                    debugLog(`✓ Table '${tableName}' exists`);
+                }
+            });
+            this.initialized = true;
+            debugLog('FSS Link database initialization completed successfully');
+        }
+        catch (error) {
+            console.error('Database initialization failed:', error);
+            this.initialized = false;
+            throw error;
+        }
     }
     /**
      * Ensure database is initialized
@@ -258,6 +301,18 @@ export class FSSLinkDatabase {
         UNIQUE(provider_id, setting_key)
       )
     `);
+        // Provider usage stats table (safety fallback if migrations failed)
+        debugLog('Creating provider_usage_stats table (legacy schema fallback)...');
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS provider_usage_stats (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        provider_id INTEGER NOT NULL,
+        tokens_used INTEGER DEFAULT 0,
+        session_duration_seconds INTEGER DEFAULT 0,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      )
+    `);
+        debugLog('provider_usage_stats table exists (legacy schema)');
         // Create indexes for performance
         this.db.exec(`
       CREATE INDEX IF NOT EXISTS idx_model_configs_active ON model_configs(is_active);
@@ -265,7 +320,7 @@ export class FSSLinkDatabase {
       CREATE INDEX IF NOT EXISTS idx_model_configs_last_used ON model_configs(last_used DESC);
       CREATE INDEX IF NOT EXISTS idx_model_configs_auth_type ON model_configs(auth_type);
       CREATE INDEX IF NOT EXISTS idx_custom_endpoints_provider ON custom_endpoints(provider_id);
-      CREATE INDEX IF NOT EXISTS idx_provider_usage_date ON provider_usage(session_date DESC);
+      CREATE INDEX IF NOT EXISTS idx_provider_usage_stats_aggregation ON provider_usage_stats(provider_id, created_at DESC);
       CREATE INDEX IF NOT EXISTS idx_provider_settings_key ON provider_settings(provider_id, setting_key);
     `);
         // Insert default configurations if none exist
@@ -279,10 +334,9 @@ export class FSSLinkDatabase {
     async ensureDefaultConfigurations() {
         if (!this.db)
             return;
-        // Check if any configurations exist
-        const countStmt = this.db.prepare('SELECT COUNT(*) as count FROM model_configs');
-        const countResult = countStmt.getAsObject({});
-        if (countResult.count === 0) {
+        // MIGRATED: Check if any configurations exist
+        const countResult = safeQueryFirst(this.db, 'SELECT COUNT(*) as count FROM model_configs');
+        if ((countResult?.count || 0) === 0) {
             // Insert default Ollama configuration for new users (no API key needed)
             const defaultOllamaConfig = {
                 auth_type: 'ollama',
@@ -295,13 +349,13 @@ export class FSSLinkDatabase {
                 last_used: null,
                 created_at: new Date().toISOString()
             };
-            const insertStmt = this.db.prepare(`
+            // MIGRATED: Insert default Ollama configuration
+            safeExec(this.db, `
         INSERT INTO model_configs (
           auth_type, model_name, endpoint_url, api_key, display_name,
           is_favorite, is_active, last_used, created_at
         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `);
-            insertStmt.run([
+      `, [
                 defaultOllamaConfig.auth_type,
                 defaultOllamaConfig.model_name,
                 defaultOllamaConfig.endpoint_url,
@@ -312,10 +366,8 @@ export class FSSLinkDatabase {
                 defaultOllamaConfig.last_used,
                 defaultOllamaConfig.created_at
             ]);
-            // Get the inserted Ollama config ID to add provider settings
-            const idStmt = this.db.prepare('SELECT last_insert_rowid() as id');
-            const idResult = idStmt.getAsObject({});
-            const ollamaId = idResult.id;
+            // MIGRATED: Get the inserted Ollama config ID
+            const ollamaId = getLastInsertId(this.db);
             // Also insert a default Gemini configuration (inactive) for when users want to configure API keys later
             const defaultGeminiConfig = {
                 auth_type: 'gemini-api-key',
@@ -328,7 +380,13 @@ export class FSSLinkDatabase {
                 last_used: null,
                 created_at: new Date().toISOString()
             };
-            insertStmt.run([
+            // MIGRATED: Insert default Gemini configuration
+            safeExec(this.db, `
+        INSERT INTO model_configs (
+          auth_type, model_name, endpoint_url, api_key, display_name,
+          is_favorite, is_active, last_used, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `, [
                 defaultGeminiConfig.auth_type,
                 defaultGeminiConfig.model_name,
                 defaultGeminiConfig.endpoint_url,
@@ -351,7 +409,13 @@ export class FSSLinkDatabase {
                 last_used: null,
                 created_at: new Date().toISOString()
             };
-            insertStmt.run([
+            // MIGRATED: Insert default LM Studio configuration
+            safeExec(this.db, `
+        INSERT INTO model_configs (
+          auth_type, model_name, endpoint_url, api_key, display_name,
+          is_favorite, is_active, last_used, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `, [
                 defaultLMStudioConfig.auth_type,
                 defaultLMStudioConfig.model_name,
                 defaultLMStudioConfig.endpoint_url,
@@ -374,7 +438,13 @@ export class FSSLinkDatabase {
                 last_used: null,
                 created_at: new Date().toISOString()
             };
-            insertStmt.run([
+            // MIGRATED: Insert default OpenAI configuration
+            safeExec(this.db, `
+        INSERT INTO model_configs (
+          auth_type, model_name, endpoint_url, api_key, display_name,
+          is_favorite, is_active, last_used, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `, [
                 defaultOpenAIConfig.auth_type,
                 defaultOpenAIConfig.model_name,
                 defaultOpenAIConfig.endpoint_url,
@@ -385,30 +455,35 @@ export class FSSLinkDatabase {
                 defaultOpenAIConfig.last_used,
                 defaultOpenAIConfig.created_at
             ]);
-            // Get the LM Studio ID
-            const lmStudioStmt = this.db.prepare('SELECT last_insert_rowid() as id');
-            const lmStudioResult = lmStudioStmt.getAsObject({});
-            const lmStudioId = lmStudioResult.id;
-            // Insert default provider settings for optimal context windows
-            const settingsStmt = this.db.prepare(`
-        INSERT INTO provider_settings (provider_id, setting_key, setting_value, updated_at)
-        VALUES (?, ?, ?, ?)
-      `);
+            // MIGRATED: Get the LM Studio ID
+            const lmStudioId = getLastInsertId(this.db);
+            // MIGRATED: Insert default provider settings for optimal context windows
             const now = new Date().toISOString();
             // Ollama default settings - 32K context window
-            settingsStmt.run([ollamaId, 'num_ctx', '32768', now]);
-            settingsStmt.run([ollamaId, 'temperature', '0.0', now]);
+            safeExec(this.db, `
+        INSERT INTO provider_settings (provider_id, setting_key, setting_value, updated_at)
+        VALUES (?, ?, ?, ?)
+      `, [ollamaId, 'num_ctx', '32768', now]);
+            safeExec(this.db, `
+        INSERT INTO provider_settings (provider_id, setting_key, setting_value, updated_at)
+        VALUES (?, ?, ?, ?)
+      `, [ollamaId, 'temperature', '0.0', now]);
             // LM Studio default settings - 32K context window
-            settingsStmt.run([lmStudioId, 'num_ctx', '32768', now]);
-            settingsStmt.run([lmStudioId, 'temperature', '0.0', now]);
+            safeExec(this.db, `
+        INSERT INTO provider_settings (provider_id, setting_key, setting_value, updated_at)
+        VALUES (?, ?, ?, ?)
+      `, [lmStudioId, 'num_ctx', '32768', now]);
+            safeExec(this.db, `
+        INSERT INTO provider_settings (provider_id, setting_key, setting_value, updated_at)
+        VALUES (?, ?, ?, ?)
+      `, [lmStudioId, 'temperature', '0.0', now]);
         }
-        // CRITICAL: ALWAYS ensure there's an active model (even if configs already exist)
-        const activeStmt = this.db.prepare('SELECT COUNT(*) as count FROM model_configs WHERE is_active = 1');
-        const activeResult = activeStmt.getAsObject({});
-        if (activeResult.count === 0) {
-            // No active model found - activate the best available model
+        // MIGRATED: ALWAYS ensure there's an active model (even if configs already exist)
+        const activeResult = safeQueryFirst(this.db, 'SELECT COUNT(*) as count FROM model_configs WHERE is_active = 1');
+        if ((activeResult?.count || 0) === 0) {
+            // MIGRATED: No active model found - activate the best available model
             // Priority: Ollama > LM Studio > Gemini > OpenAI
-            const findBestStmt = this.db.prepare(`
+            const bestModel = safeQueryFirst(this.db, `
         SELECT id FROM model_configs 
         WHERE auth_type IN ('ollama', 'lmstudio', 'gemini-api-key', 'openai-api-key')
         ORDER BY 
@@ -422,56 +497,51 @@ export class FSSLinkDatabase {
           created_at ASC 
         LIMIT 1
       `);
-            if (findBestStmt.step()) {
-                const bestModel = findBestStmt.getAsObject();
-                this.db.run('UPDATE model_configs SET is_active = 1 WHERE id = ?', [bestModel.id]);
-                // Add default provider settings if they don't exist
-                const settingsCheckStmt = this.db.prepare('SELECT COUNT(*) as count FROM provider_settings WHERE provider_id = ?');
-                settingsCheckStmt.bind([bestModel.id]);
-                if (settingsCheckStmt.step()) {
-                    const settingsCheck = settingsCheckStmt.getAsObject();
-                    if (settingsCheck.count === 0) {
-                        const now = new Date().toISOString();
-                        const addSettingsStmt = this.db.prepare('INSERT INTO provider_settings (provider_id, setting_key, setting_value, updated_at) VALUES (?, ?, ?, ?)');
-                        addSettingsStmt.run([bestModel.id, 'num_ctx', '32768', now]);
-                        addSettingsStmt.run([bestModel.id, 'temperature', '0.0', now]);
-                    }
+            if (bestModel) {
+                safeExec(this.db, 'UPDATE model_configs SET is_active = 1 WHERE id = ?', [bestModel.id]);
+                // MIGRATED: Add default provider settings if they don't exist
+                const settingsCheck = safeQueryFirst(this.db, 'SELECT COUNT(*) as count FROM provider_settings WHERE provider_id = ?', [bestModel.id]);
+                if ((settingsCheck?.count || 0) === 0) {
+                    const now = new Date().toISOString();
+                    safeExec(this.db, 'INSERT INTO provider_settings (provider_id, setting_key, setting_value, updated_at) VALUES (?, ?, ?, ?)', [bestModel.id, 'num_ctx', '32768', now]);
+                    safeExec(this.db, 'INSERT INTO provider_settings (provider_id, setting_key, setting_value, updated_at) VALUES (?, ?, ?, ?)', [bestModel.id, 'temperature', '0.0', now]);
                 }
             }
         }
     }
     /**
      * Get provider settings for a specific provider
+     * @todo UPGRADE: Move to ProviderSettingsRepository.findByProviderId()
      */
     async getProviderSettings(providerId) {
         await this.ensureInitialized();
         if (!this.db)
             return {};
-        const stmt = this.db.prepare(`
+        // MIGRATED: Using safeQuery wrapper to eliminate manual .free() calls
+        const rows = safeQuery(this.db, `
       SELECT setting_key, setting_value 
       FROM provider_settings 
       WHERE provider_id = ?
-    `);
-        stmt.bind([providerId]);
+    `, [providerId]);
         const settings = {};
-        while (stmt.step()) {
-            const row = stmt.getAsObject();
+        for (const row of rows) {
             settings[row.setting_key] = row.setting_value;
         }
         return settings;
     }
     /**
      * Save a provider setting
+     * @todo UPGRADE: Move to ProviderSettingsRepository.upsert()
      */
     async saveProviderSetting(providerId, key, value) {
         await this.ensureInitialized();
         if (!this.db)
             return;
-        const stmt = this.db.prepare(`
+        // MIGRATED: Using safeExec wrapper to eliminate manual .free() calls
+        safeExec(this.db, `
       INSERT OR REPLACE INTO provider_settings (provider_id, setting_key, setting_value, updated_at)
       VALUES (?, ?, ?, ?)
-    `);
-        stmt.run([providerId, key, String(value), new Date().toISOString()]);
+    `, [providerId, key, String(value), new Date().toISOString()]);
     }
     /**
      * Get the currently active model configuration
@@ -509,6 +579,7 @@ export class FSSLinkDatabase {
     }
     /**
      * Add or update a model configuration
+     * @todo UPGRADE: Move to ModelRepository.upsert()
      */
     async upsertModelConfig(config) {
         await this.ensureInitialized();
@@ -516,12 +587,12 @@ export class FSSLinkDatabase {
             return -1;
         // Encrypt API key if provided
         const encryptedApiKey = config.apiKey ? this.encryptApiKey(config.apiKey) : null;
-        const stmt = this.db.prepare(`
+        // MIGRATED: Using safeExec wrapper to eliminate manual .free() calls
+        safeExec(this.db, `
       INSERT OR REPLACE INTO model_configs 
       (auth_type, model_name, endpoint_url, api_key, display_name, is_favorite, is_active, last_used, source)
       VALUES (?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP, ?)
-    `);
-        stmt.run([
+    `, [
             config.authType,
             config.modelName,
             config.endpointUrl || null,
@@ -532,9 +603,8 @@ export class FSSLinkDatabase {
             config.source || 'db'
         ]);
         this.save();
-        // Get the last inserted row ID
-        const result = this.db.exec('SELECT last_insert_rowid() as id');
-        return result[0]?.values[0]?.[0] || -1;
+        // MIGRATED: Get the last inserted row ID using helper
+        return getLastInsertId(this.db);
     }
     /**
      * Get all model configurations
@@ -557,29 +627,28 @@ export class FSSLinkDatabase {
      */
     async getFavoriteModels() {
         await this.ensureInitialized();
-        if (!this.db)
-            return [];
-        const stmt = this.db.prepare(`
-      SELECT id, auth_type, model_name, endpoint_url, api_key, display_name,
-             is_favorite, is_active, last_used, created_at, source
-      FROM model_configs 
-      WHERE is_favorite = 1
-      ORDER BY last_used DESC, created_at DESC
-    `);
-        const results = [];
-        while (stmt.step()) {
-            results.push(this.mapRowToModelConfig(stmt.getAsObject()));
-        }
-        return results;
+        return await this.pool.withConnection(async (db) => {
+            const query = `
+        SELECT id, auth_type, model_name, endpoint_url, api_key, display_name,
+               is_favorite, is_active, last_used, created_at, source
+        FROM model_configs 
+        WHERE is_favorite = 1
+        ORDER BY last_used DESC, created_at DESC
+      `;
+            const results = await this.queryOptimizer.executeQuery(db, query);
+            return results.map(row => this.mapRowToModelConfig(row));
+        });
     }
     /**
      * Get recently used models
+     * @todo UPGRADE: Move to ModelRepository.findRecentlyUsed()
      */
     async getRecentModels(limit = 10) {
         await this.ensureInitialized();
         if (!this.db)
             return [];
-        const stmt = this.db.prepare(`
+        // MIGRATED: Using safeQuery wrapper to eliminate manual .free() calls
+        const rows = safeQuery(this.db, `
       SELECT id, auth_type, model_name, endpoint_url, api_key, display_name,
              is_favorite, is_active, last_used, created_at, source
       FROM model_configs 
@@ -587,11 +656,7 @@ export class FSSLinkDatabase {
       ORDER BY last_used DESC
       LIMIT ?
     `, [limit]);
-        const results = [];
-        while (stmt.step()) {
-            results.push(this.mapRowToModelConfig(stmt.getAsObject()));
-        }
-        return results;
+        return rows.map(row => this.mapRowToModelConfig(row));
     }
     /**
      * Toggle favorite status for a model
@@ -631,30 +696,29 @@ export class FSSLinkDatabase {
         this.save();
     }
     /**
-     * Get user preference
+     * Get user preference by key
+     * @todo UPGRADE: Move to PreferencesRepository.findByKey()
      */
     async getUserPreference(key) {
         await this.ensureInitialized();
         if (!this.db)
             return null;
-        const stmt = this.db.prepare('SELECT value FROM user_preferences WHERE key = ?', [key]);
-        if (stmt.step()) {
-            const result = stmt.getAsObject();
-            return result.value || null;
-        }
-        return null;
+        // MIGRATED: Using safeQueryFirst wrapper to eliminate manual .free() calls
+        const result = safeQueryFirst(this.db, 'SELECT value FROM user_preferences WHERE key = ?', [key]);
+        return result?.value || null;
     }
     /**
      * Get all user preferences
+     * @todo UPGRADE: Move to PreferencesRepository.findAll()
      */
     async getAllUserPreferences() {
         await this.ensureInitialized();
         if (!this.db)
             return {};
-        const stmt = this.db.prepare('SELECT key, value FROM user_preferences');
+        // MIGRATED: Using safeQuery wrapper to eliminate manual .free() calls
+        const rows = safeQuery(this.db, 'SELECT key, value FROM user_preferences');
         const prefs = {};
-        while (stmt.step()) {
-            const row = stmt.getAsObject();
+        for (const row of rows) {
             prefs[row.key] = row.value;
         }
         return prefs;
@@ -811,26 +875,72 @@ export class FSSLinkDatabase {
      * Record provider usage for intelligent default selection
      */
     async recordProviderUsage(providerId, tokensUsed, sessionDuration) {
-        await this.ensureInitialized();
-        if (!this.db)
-            return;
-        // Update or insert daily usage statistics
-        this.db.exec(`
-      INSERT INTO provider_usage (provider_id, tokens_used, session_duration)
-      VALUES (?, ?, ?)
-      ON CONFLICT(provider_id, session_date)
-      DO UPDATE SET 
-        session_count = session_count + 1,
-        tokens_used = tokens_used + excluded.tokens_used,
-        session_duration = session_duration + excluded.session_duration
-    `, [providerId, tokensUsed, sessionDuration]);
-        // Update last_used timestamp in model_configs
-        this.db.exec(`
-      UPDATE model_configs 
-      SET last_used = CURRENT_TIMESTAMP 
-      WHERE id = ?
-    `, [providerId]);
-        this.save();
+        console.log(`recordProviderUsage called: providerId=${providerId}, tokensUsed=${tokensUsed}, sessionDuration=${sessionDuration}`);
+        try {
+            // Ensure database is fully initialized including migrations
+            debugLog('Ensuring database is initialized for usage recording...');
+            await this.ensureInitialized();
+            // Triple-check initialization completed with detailed logging
+            if (!this.initialized) {
+                console.warn('Database not initialized after ensureInitialized(), skipping usage recording');
+                return;
+            }
+            debugLog('Database initialized, attempting to record usage...');
+            await this.pool.withConnection(async (db) => {
+                // Check if table exists before trying to use it
+                debugLog('Checking if provider_usage_stats table exists...');
+                const tableCheck = db.exec(`
+          SELECT name FROM sqlite_master 
+          WHERE type='table' AND name='provider_usage_stats'
+        `);
+                if (tableCheck.length === 0) {
+                    console.error('provider_usage_stats table does not exist, this should not happen after initialization!');
+                    // Emergency table creation as absolute last resort
+                    console.log('Attempting emergency table creation...');
+                    try {
+                        db.exec(`
+              CREATE TABLE IF NOT EXISTS provider_usage_stats (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                provider_id INTEGER NOT NULL,
+                tokens_used INTEGER DEFAULT 0,
+                session_duration_seconds INTEGER DEFAULT 0,
+                created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+              )
+            `);
+                        console.log('Emergency table creation completed');
+                    }
+                    catch (emergencyError) {
+                        console.error('Emergency table creation failed:', emergencyError);
+                        return;
+                    }
+                }
+                else {
+                    debugLog('provider_usage_stats table exists, proceeding with insert');
+                }
+                // MIGRATED: Insert usage statistics and update timestamp in transaction
+                console.log('Inserting usage statistics and updating timestamp...');
+                safeTransaction(db, () => {
+                    // Insert usage statistics
+                    safeExec(db, `
+            INSERT INTO provider_usage_stats (provider_id, tokens_used, session_duration_seconds, created_at)
+            VALUES (?, ?, ?, CURRENT_TIMESTAMP)
+          `, [providerId, tokensUsed, sessionDuration]);
+                    // Update last_used timestamp in model_configs
+                    safeExec(db, `
+            UPDATE model_configs 
+            SET last_used = CURRENT_TIMESTAMP 
+            WHERE id = ?
+          `, [providerId]);
+                });
+                console.log('Usage statistics and timestamp updated successfully');
+            });
+            this.scheduleBatchedSave();
+            console.log('Provider usage recording completed successfully');
+        }
+        catch (error) {
+            console.error('Failed to record provider usage (detailed error):', error);
+            console.error('Error stack:', error instanceof Error ? error.stack : 'No stack trace');
+        }
     }
     /**
      * Save custom endpoint for a provider
@@ -857,24 +967,19 @@ export class FSSLinkDatabase {
     }
     /**
      * Get custom endpoints for a provider
+     * @todo UPGRADE: Move to CustomEndpointsRepository.findByProviderId()
      */
     async getCustomEndpoints(providerId) {
         await this.ensureInitialized();
         if (!this.db)
             return [];
-        const stmt = this.db.prepare(`
+        // MIGRATED: Using safeQuery wrapper to eliminate manual .free() calls
+        return safeQuery(this.db, `
       SELECT id, provider_id, name, url, description, is_default, created_at
       FROM custom_endpoints
       WHERE provider_id = ?
       ORDER BY is_default DESC, created_at DESC
-    `);
-        stmt.bind([providerId]);
-        const endpoints = [];
-        while (stmt.step()) {
-            const row = stmt.getAsObject();
-            endpoints.push(row);
-        }
-        return endpoints;
+    `, [providerId]);
     }
     /**
      * Get smart default provider with settings
@@ -888,16 +993,17 @@ export class FSSLinkDatabase {
     }
     /**
      * Get smart default provider based on usage and preferences
+     * @todo UPGRADE: Move to ModelRepository.findSmartDefault()
      */
     async getSmartDefaultProvider() {
         await this.ensureInitialized();
         if (!this.db)
             return null;
-        // Priority order:
+        // MIGRATED: Priority order using safeQueryFirst wrapper
         // 1. User-marked favorite (is_favorite = 1)
         // 2. Most used provider in last 30 days
         // 3. Most recently used provider
-        const stmt = this.db.prepare(`
+        const result = safeQueryFirst(this.db, `
       SELECT 
         m.id, m.auth_type, m.model_name, m.endpoint_url, m.api_key, 
         m.display_name, m.is_favorite, m.is_active, m.last_used, m.created_at,
@@ -918,9 +1024,8 @@ export class FSSLinkDatabase {
         m.created_at DESC
       LIMIT 1
     `);
-        if (!stmt.step())
+        if (!result)
             return null;
-        const result = stmt.getAsObject();
         return {
             id: result.id,
             authType: result.auth_type,
@@ -934,18 +1039,18 @@ export class FSSLinkDatabase {
     }
     /**
      * Get a specific model configuration by ID
+     * @todo UPGRADE: Move to ModelRepository.findById()
      */
     async getModelById(modelId) {
         await this.ensureInitialized();
         if (!this.db)
             return null;
-        const stmt = this.db.prepare(`
+        // MIGRATED: Using safeQueryFirst wrapper to eliminate manual .free() calls
+        const result = safeQueryFirst(this.db, `
       SELECT * FROM model_configs WHERE id = ?
-    `);
-        stmt.bind([modelId]);
-        if (!stmt.step())
+    `, [modelId]);
+        if (!result)
             return null;
-        const result = stmt.getAsObject();
         return {
             id: result.id,
             authType: result.auth_type,
@@ -957,7 +1062,238 @@ export class FSSLinkDatabase {
             isActive: Boolean(result.is_active)
         };
     }
+    /**
+     * Get query performance metrics from the optimizer
+     */
+    async getQueryMetrics() {
+        return this.queryOptimizer.getQueryMetrics();
+    }
+    /**
+     * Get slow queries (above threshold)
+     */
+    async getSlowQueries(thresholdMs = 100) {
+        return this.queryOptimizer.getSlowQueries(thresholdMs);
+    }
+    /**
+     * Get most frequently executed queries
+     */
+    async getFrequentQueries(limit = 10) {
+        return this.queryOptimizer.getFrequentQueries(limit);
+    }
+    /**
+     * Get prepared statement cache statistics
+     */
+    async getCacheStats() {
+        return this.queryOptimizer.getCacheStats();
+    }
+    /**
+     * Clear query performance metrics
+     */
+    async clearQueryMetrics() {
+        this.queryOptimizer.clearMetrics();
+    }
+    /**
+     * Optimize database by running ANALYZE
+     */
+    async optimizeDatabase() {
+        await this.pool.withConnection(async (db) => {
+            await this.queryOptimizer.optimizeDatabase(db);
+        });
+    }
+    /**
+     * Get comprehensive database statistics
+     */
+    async getDatabaseStats() {
+        return await this.pool.withConnection(async (db) => {
+            return await this.queryOptimizer.getDatabaseStats(db);
+        });
+    }
+    /**
+     * Run VACUUM to reclaim space and defragment
+     */
+    async vacuumDatabase() {
+        await this.pool.withConnection(async (db) => {
+            await this.queryOptimizer.vacuumDatabase(db);
+        });
+    }
+    /**
+     * Collect comprehensive database metrics
+     */
+    async collectMetrics() {
+        return await this.pool.withConnection(async (db) => {
+            return await this.metricsCollector.collectMetrics(db, this.queryOptimizer, this.pool, this.backupManager);
+        });
+    }
+    /**
+     * Get historical metrics for trend analysis
+     */
+    async getHistoricalMetrics(hours = 24) {
+        return this.metricsCollector.getHistoricalMetrics(hours);
+    }
+    /**
+     * Get performance trends
+     */
+    async getPerformanceTrends(hours = 24) {
+        return this.metricsCollector.getPerformanceTrends(hours);
+    }
+    /**
+     * Generate a comprehensive database health report
+     */
+    async generateHealthReport() {
+        const metrics = await this.collectMetrics();
+        const trends = await this.getPerformanceTrends();
+        const recommendations = [];
+        // Generate recommendations based on metrics
+        if (metrics.queryPerformance.averageQueryTime > 100) {
+            recommendations.push('Consider running ANALYZE to optimize query plans');
+        }
+        if (metrics.cachePerformance.hitRate < 80) {
+            recommendations.push('Increase prepared statement cache size for better performance');
+        }
+        if (metrics.connectionPool.connectionUtilization > 90) {
+            recommendations.push('Consider increasing database connection pool size');
+        }
+        if (metrics.database.freelistCount > 1000) {
+            recommendations.push('Run VACUUM to reclaim unused database space');
+        }
+        if (metrics.usage.lastBackupAge > 24) {
+            recommendations.push('Create a fresh backup - last backup is over 24 hours old');
+        }
+        if (metrics.health.overallScore < 70) {
+            recommendations.push('Database health is below optimal - consider maintenance');
+        }
+        return {
+            metrics,
+            trends,
+            recommendations
+        };
+    }
+    /**
+     * Set custom metrics thresholds
+     */
+    async setMetricsThresholds(thresholds) {
+        this.metricsCollector.setThresholds(thresholds);
+    }
+    /**
+     * Clear metrics history (for testing or cleanup)
+     */
+    async clearMetricsHistory() {
+        this.metricsCollector.clearHistory();
+    }
+    /**
+     * Perform comprehensive health check
+     */
+    async performHealthCheck() {
+        const metrics = await this.collectMetrics();
+        return await this.healthMonitor.checkHealth(metrics);
+    }
+    /**
+     * Get maintenance recommendations
+     */
+    async getMaintenanceRecommendations() {
+        const metrics = await this.collectMetrics();
+        return this.healthMonitor.getMaintenanceRecommendations(metrics);
+    }
+    /**
+     * Get recent health check history
+     */
+    async getHealthHistory(hours = 24) {
+        return this.healthMonitor.getRecentHealthChecks(hours);
+    }
+    /**
+     * Update health monitoring thresholds
+     */
+    async updateHealthThresholds(thresholds) {
+        this.healthMonitor.updateThresholds(thresholds);
+    }
+    /**
+     * Clear health monitoring history
+     */
+    async clearHealthHistory() {
+        this.healthMonitor.clearHistory();
+    }
+    /**
+     * Validate database schema against expected structure
+     */
+    async validateSchema() {
+        return await this.pool.withConnection(async (db) => {
+            return await this.schemaValidator.validateSchema(db);
+        });
+    }
+    /**
+     * Validate specific table schema
+     */
+    async validateTableSchema(tableName) {
+        return await this.pool.withConnection(async (db) => {
+            return await this.schemaValidator.validateTableSchema(db, tableName);
+        });
+    }
+    /**
+     * Check if database needs migration based on schema validation
+     */
+    async needsSchemaMigration() {
+        return await this.pool.withConnection(async (db) => {
+            return await this.schemaValidator.needsMigration(db);
+        });
+    }
+    /**
+     * Get missing tables from schema
+     */
+    async getMissingTables() {
+        return await this.pool.withConnection(async (db) => {
+            return await this.schemaValidator.getMissingTables(db);
+        });
+    }
+    /**
+     * Get missing indexes from schema
+     */
+    async getMissingIndexes() {
+        return await this.pool.withConnection(async (db) => {
+            return await this.schemaValidator.getMissingIndexes(db);
+        });
+    }
+    /**
+     * Get formatted schema validation report
+     */
+    async getSchemaValidationReport() {
+        const result = await this.validateSchema();
+        return this.schemaValidator.formatValidationReport(result);
+    }
+    /**
+     * Perform comprehensive database integrity check
+     */
+    async performIntegrityCheck() {
+        // Run all checks in parallel
+        const [schemaValidation, healthCheck, recommendations] = await Promise.all([
+            this.validateSchema(),
+            this.performHealthCheck(),
+            this.getMaintenanceRecommendations()
+        ]);
+        // Determine overall status
+        let overallStatus = 'healthy';
+        if (!schemaValidation.isValid ||
+            healthCheck.some(h => h.status === 'critical' || h.status === 'error')) {
+            overallStatus = 'critical';
+        }
+        else if (schemaValidation.warnings.length > 0 ||
+            healthCheck.some(h => h.status === 'warning') ||
+            recommendations.length > 0) {
+            overallStatus = 'warning';
+        }
+        return {
+            schemaValidation,
+            healthCheck,
+            recommendations,
+            overallStatus
+        };
+    }
 }
+// Debug logging helper - only log if DEBUG environment variable is set
+const debugLog = (message) => {
+    if (process.env['DEBUG'] === '1' || process.env['DEBUG'] === 'true') {
+        console.log(`[DB] ${message}`);
+    }
+};
 // Singleton instance for global access
 let databaseInstance = null;
 /**
@@ -965,8 +1301,11 @@ let databaseInstance = null;
  */
 export async function getFSSLinkDatabase() {
     if (!databaseInstance) {
+        debugLog('Creating new FSS Link database instance...');
         databaseInstance = new FSSLinkDatabase();
+        debugLog('Initializing FSS Link database...');
         await databaseInstance.initialize();
+        debugLog('FSS Link database ready for use');
     }
     return databaseInstance;
 }