kythia-core 0.9.3-beta

package/src/database/KythiaORM.js

@@ -0,0 +1,481 @@
+/**
+ * 🧠 Smart Sequelize Sync Utility
+ *
+ * @file src/database/KythiaORM.js
+ * @copyright © 2025 kenndeclouv
+ * @assistant chaa & graa
+ * @version 0.9.3-beta
+ *
+ * @description
+ * A utility for intelligent, hash-based syncing of Sequelize models.
+ * Only models with schema changes are synced, minimizing downtime and risk.
+ *
+ * ✨ Core Features:
+ * - Per-model schema hashing for change detection.
+ * - Selective, safe syncing (avoids unnecessary ALTERs).
+ * - Designed for production safety and speed.
+ * - No destructive operations; only additive/compatible changes are auto-applied.
+ * - Detailed logging for each sync operation.
+ */
+const readline = require('readline');
+const crypto = require('crypto');
+const path = require('path');
+const fs = require('fs');
+const { existsSync, readdirSync, statSync } = fs;
+
+/**
+ * 🧬 generateModelHash
+ *
+ * Generates a unique, deterministic hash for a single Sequelize model's schema definition.
+ *
+ * - **Purpose:**
+ *   Detects changes in a model's structure (attributes, associations, indexes) so that only changed models are synced.
+ *
+ * - **How it works:**
+ *   1. **Attributes:**
+ *      - Iterates all model attributes, sorts them, and serializes their type, nullability, primary/unique status.
+ *      - Handles Sequelize's type objects robustly (tries `.toSql()`, then `.toString()`, else "UnknownType").
+ *   2. **Associations:**
+ *      - Serializes all associations (type, alias, target model, foreign key), sorted by alias.
+ *   3. **Indexes:**
+ *      - Serializes all indexes (name, fields, uniqueness), sorted by name.
+ *   4. **Table Name:**
+ *      - Ensures table name is always a string.
+ *   5. **Hashing:**
+ *      - Concatenates all above into a single string, then hashes with MD5 (first 10 chars).
+ *
+ * - **Why:**
+ *   This ensures that any schema change (even subtle) will result in a new hash, triggering a sync for that model only.
+ *
+ * @param {import('sequelize').ModelCtor} model - The Sequelize model to hash.
+ * @returns {string} - A short MD5 hash representing the model's schema state.
+ */
+function generateModelHash(model) {
+    const attributes = Object.entries(model.rawAttributes)
+        .sort()
+        .map(([attrName, attr]) => {
+            let typeString;
+            try {
+                if (typeof attr.type?.toSql === 'function') {
+                    try {
+                        typeString = attr.type.toSql({});
+                    } catch (e) {
+                        typeString = attr.type.toString();
+                    }
+                } else if (typeof attr.type?.toString === 'function') {
+                    typeString = attr.type.toString();
+                } else {
+                    typeString = 'UnknownType';
+                }
+            } catch (err) {
+                typeString = 'UnknownType';
+            }
+            return `${attrName}:${typeString}:${!!attr.allowNull}:${!!attr.primaryKey}:${!!attr.unique}`;
+        })
+        .join(',');
+
+    const associations = Object.values(model.associations || {})
+        .sort((a, b) => (a.as || '').localeCompare(b.as || ''))
+        .map((assoc) => `${assoc.associationType}:${assoc.as}:${assoc.target.name}:${assoc.foreignKey}`)
+        .join(',');
+
+    const indexes = (model.options.indexes || [])
+        .sort((a, b) => (a.name || '').localeCompare(b.name || ''))
+        .map((idx) => {
+            const fields = Array.isArray(idx.fields) ? idx.fields.join(',') : '';
+            return `${idx.name || fields}:${fields}:${!!idx.unique}`;
+        })
+        .join(',');
+
+    let tableName = model.getTableName();
+    if (typeof tableName === 'object') tableName = tableName.tableName;
+
+    const definitionString = `${tableName}:{attr:{${attributes}},assoc:{${associations}},idx:{${indexes}}}`;
+    return crypto.createHash('md5').update(definitionString).digest('hex').substring(0, 10);
+}
+
+/**
+ * 📦 loadAllAddonModels
+ *
+ * Dynamically loads all Sequelize models from every addon's `database/models` directory.
+ *
+ * - **Purpose:**
+ *   Ensures that all models from all installed addons are registered with Sequelize before syncing.
+ *
+ * - **How it works:**
+ *   1. Looks for the `addons` directory in the given root.
+ *   2. For each addon folder, checks for a `database/models` subdirectory.
+ *   3. Requires every `.js` file in that directory, which should register the model with Sequelize.
+ *   4. Logs each loaded model for visibility.
+ *
+ * - **Why:**
+ *   This allows the system to support modular, pluggable features (addons) with their own database models.
+ *
+ * @param {string} rootDir - The root directory of the project.
+ * @param {Object} sequelize - Sequelize instance
+ * @param {Object} logger - Logger instance
+ */
+function loadAllAddonModels(rootDir, sequelize, logger) {
+    const addonsDir = path.join(rootDir, 'addons');
+    if (!existsSync(addonsDir)) return;
+
+    const addonFolders = readdirSync(addonsDir, { withFileTypes: true })
+        .filter((dirent) => dirent.isDirectory())
+        .map((dirent) => dirent.name);
+
+    for (const addonName of addonFolders) {
+        const modelsDir = path.join(addonsDir, addonName, 'database', 'models');
+        if (existsSync(modelsDir) && statSync(modelsDir).isDirectory()) {
+            logger.info(`📂 Loading models from addon: ${addonName}`);
+            const files = readdirSync(modelsDir).filter((file) => file.endsWith('.js'));
+
+            for (const file of files) {
+                const modelPath = path.join(modelsDir, file);
+                try {
+                    const modelClass = require(modelPath);
+
+                    if (modelClass && typeof modelClass.init === 'function') {
+                        modelClass.init(sequelize);
+
+                        logger.info(`  └─> Initialized model: ${file}`);
+                    } else {
+                        logger.warn(`  └─> File ${file} is not a valid model class, skipping init.`);
+                    }
+                } catch (err) {
+                    logger.error(`  └─> ❌ Failed to load or init model: ${file}`, err.message);
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Helper: Interactive prompt for production force sync
+ * @param {Array<string>} changedModels - Array of model names that will be synced
+ * @param {Object} logger - Logger instance
+ * @returns {Promise<boolean>}
+ */
+async function askForProductionSyncConfirmation(changedModels, logger) {
+    const readline = require('readline');
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+
+    return new Promise((resolve) => {
+        logger.warn('\n==================== 🚨 PRODUCTION WARNING 🚨 ====================');
+        logger.warn(`Database schema for [${changedModels.join(', ')}] is OUT OF DATE.`);
+        logger.warn('You are about to ALTER tables in PRODUCTION.');
+        logger.warn('This operation may be risky. Please ensure you have a backup.');
+        logger.warn('==================================================================');
+
+        rl.question('Do you want to continue with force sync? (y/N): ', (answer) => {
+            rl.close();
+            const normalized = answer.trim().toLowerCase();
+            if (normalized === 'y' || normalized === 'yes') {
+                resolve(true);
+            } else {
+                logger.error('❌ Force sync aborted by user.');
+                resolve(false);
+            }
+        });
+    });
+}
+
+/**
+ * Helper: Interactive prompt for destructive changes (column removal)
+ * @param {string} modelName - Name of the model with potential destructive changes
+ * @param {Array<string>} droppedColumns - Array of column names that would be dropped
+ * @param {Object} logger - Logger instance
+ * @returns {Promise<boolean>}
+ */
+async function askForDestructiveChangeConfirmation(modelName, droppedColumns, logger) {
+    const readline = require('readline');
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+
+    return new Promise((resolve) => {
+        logger.error(`\n==================== ⚠️ DANGEROUS CHANGE WARNING ⚠️ ====================`);
+        logger.error(`Model '${modelName}' detected potential COLUMN REMOVAL:`);
+        logger.error(` -> ${droppedColumns.join(', ')}`);
+        logger.error('\nThese columns exist in the database but are not found in the latest model file.');
+        logger.error('To prevent data loss, automatic sync is blocked by default.');
+        logger.error('\nSOLUTION:');
+        logger.error('1. If this is a mistake, fix your model file to include these columns.');
+        logger.error('2. If you are SURE you want to remove these columns, you can continue, but data will be lost.');
+        logger.error('================================================================================\n');
+
+        rl.question('Do you want to continue with this destructive change? (y/N): ', (answer) => {
+            rl.close();
+            const normalized = answer.trim().toLowerCase();
+            if (normalized === 'y' || normalized === 'yes') {
+                logger.warn('⚠️  Proceeding with destructive change as requested by user.');
+                resolve(true);
+            } else {
+                logger.error('❌ Destructive change aborted by user.');
+                resolve(false);
+            }
+        });
+    });
+}
+
+/**
+ * 🚨 Safety Net: Pengecekan Perubahan Destruktif
+ *
+ * Membandingkan skema model di kode dengan skema di database.
+ * Jika ada kolom yang ada di DB tapi tidak ada di model (potensi DROP COLUMN),
+ * proses akan berhenti dengan pesan error yang jelas, atau bertanya ke user jika di production.
+ *
+ * @param {import('sequelize').ModelCtor} model - Model Sequelize yang akan dicek.
+ * @param {Object} sequelize - Sequelize instance
+ * @param {Object} logger - Logger instance
+ * @param {Object} config - Application config
+ * @returns {Promise<boolean>} - true jika aman lanjut, false jika user abort.
+ */
+
+/**
+ * 🚨 Safety Net: Pengecekan Perubahan Destruktif
+ *
+ * (Deskripsi biarin aja)
+ *
+ * @param {import('sequelize').ModelCtor} model - Model Sequelize yang akan dicek.
+ * @param {Object} sequelize - Sequelize instance
+ * @param {Object} logger - Logger instance
+ * @param {Object} config - Application config
+ * @returns {Promise<boolean>} - true jika aman lanjut, false jika user abort.
+ */
+async function checkForDestructiveChanges(model, sequelize, logger, config) {
+    const queryInterface = sequelize.getQueryInterface();
+    const tableName = model.getTableName();
+    const tableNameStr = typeof tableName === 'string' ? tableName : tableName.tableName;
+
+    try {
+        const dbSchema = await queryInterface.describeTable(tableNameStr);
+        const dbColumnNames = Object.keys(dbSchema);
+
+        const modelColumnNames = Object.keys(model.rawAttributes);
+
+        const droppedColumns = dbColumnNames.filter((col) => !modelColumnNames.includes(col));
+
+        if (droppedColumns.length > 0) {
+            if (config.env === 'production') {
+                logger.warn(`PERINGATAN PRODUKSI: Terdeteksi potensi penghapusan kolom di model ${model.name}.`);
+                return await askForDestructiveChangeConfirmation(model.name, droppedColumns, logger);
+            } else {
+                logger.warn(`\n⚠️  WARNING: Model '${model.name}' has ${droppedColumns.length} columns in DB that are not in the model.`);
+                logger.warn('This could cause data loss if columns are removed. Columns:', droppedColumns.join(', '));
+                return true;
+            }
+        }
+
+        return true;
+    } catch (error) {
+        const isTableNotFoundError =
+            (error.name === 'SequelizeDatabaseError' && error.original?.code === 'ER_NO_SUCH_TABLE') ||
+            (error.name === 'SequelizeDatabaseError' && error.original?.code === '42P01') ||
+            (typeof error.message === 'string' && error.message.match(/table.*?doesn't exist/i)) ||
+            (typeof error.message === 'string' && error.message.match(/^No description found for/i));
+
+        if (isTableNotFoundError) {
+            logger.info(` -> Table '${tableNameStr}' not found, will be created.`);
+            return true;
+        }
+
+        logger.error(`❌ Error checking for destructive changes on ${model.name}:`, error.message);
+        return false;
+    }
+}
+
+/**
+ * 🧠 KythiaORM
+ *
+ * Intelligently synchronizes the database schema on a per-model basis, only syncing models whose schema has changed.
+ *
+ * - **Purpose:**
+ *   Avoids unnecessary full-database syncs by tracking a hash of each model's schema.
+ *   Only models with a changed hash are synced, making migrations safer and faster.
+ *
+ * - **How it works:**
+ *   1. Loads all addon models so Sequelize knows about every model.
+ *   2. Ensures a `model_versions` table exists to track each model's last known schema hash.
+ *   3. For each model:
+ *      - Computes its current schema hash.
+ *      - Compares to the hash stored in `model_versions`.
+ *      - If different, adds to the sync list.
+ *   4. If any models need syncing:
+ *      - In **production**, refuses to sync unless `options.force` is true (safety net).
+ *      - Otherwise, syncs each changed model with `{ alter: true }`.
+ *      - Updates the hash in `model_versions` for each synced model (UPSERT).
+ *   5. Logs the result.
+ *
+ * - **Why:**
+ *   This approach minimizes risk in production, speeds up development, and makes schema management more robust.
+ *
+ * @param {Object} params - Parameters
+ * @param {Object} params.kythiaInstance - The main Kythia instance
+ * @param {Object} params.sequelize - Sequelize instance
+ * @param {Object} params.KythiaModel - KythiaModel class
+ * @param {Object} params.logger - Logger instance
+ * @param {Object} params.config - Application config
+ * @param {Object} [options] - Options for the sync
+ * @param {boolean} [options.force=false] - Force sync in production mode
+ * @returns {Promise<Object>} - Sequelize instance
+ */
+async function KythiaORM({ kythiaInstance, sequelize, KythiaModel, logger, config }, options = {}) {
+    try {
+        const rootDir = kythiaInstance.container.appRoot;
+
+        loadAllAddonModels(rootDir, sequelize, logger);
+
+        logger.info('↔️ Performing model associations from ready hooks...');
+
+        if (Array.isArray(kythiaInstance?.dbReadyHooks)) {
+            for (const hook of kythiaInstance.dbReadyHooks) {
+                if (typeof hook === 'function') {
+                    await hook(sequelize);
+                }
+            }
+        }
+
+        if (kythiaInstance?.client) {
+            KythiaModel.attachHooksToAllModels(sequelize, kythiaInstance.client);
+        } else {
+            logger.warn('🟠 No client instance provided, skipping model hooks attachment');
+        }
+
+        const isProduction = config.env === 'production';
+        const shouldReset = process.argv.includes('--db-reset');
+
+        try {
+            const dialect = (config.db?.driver || '').toLowerCase();
+            if (dialect === 'mysql' || dialect === 'mariadb') {
+                const dbName = config.db?.name || process.env.DB_NAME;
+                const { Sequelize } = require('sequelize');
+                const tempSequelize = new Sequelize(
+                    '',
+                    config.db?.user || process.env.DB_USER,
+                    config.db?.password || process.env.DB_PASSWORD,
+                    {
+                        host: config.db?.host || process.env.DB_HOST,
+                        port: config.db?.port || process.env.DB_PORT,
+                        dialect,
+                        logging: false,
+                        dialectOptions:
+                            config.db?.dialectOptions || (process.env.DB_DIALECT_OPTIONS ? JSON.parse(process.env.DB_DIALECT_OPTIONS) : {}),
+                        socketPath: config.db?.socketPath || process.env.DB_SOCKET_PATH,
+                    }
+                );
+
+                await tempSequelize.query(`CREATE DATABASE IF NOT EXISTS \`${dbName}\``);
+                await tempSequelize.close();
+                logger.info(`🗄️ Ensured database "${dbName}" exists.`);
+            }
+        } catch (dbCreateError) {
+            logger.error('❌ Failed to create/check database existence:', dbCreateError);
+            throw dbCreateError;
+        }
+
+        if (shouldReset) {
+            if (isProduction && !options.force) {
+                logger.error('❌ Cannot reset database in production without --force flag');
+                process.exit(1);
+            }
+
+            logger.warn('🔄 Resetting database...');
+            await sequelize.sync({ force: true });
+            logger.info('✅ Database reset complete.');
+            return sequelize;
+        }
+
+        const versionTableName = 'model_versions';
+        const versionTableExists = await sequelize
+            .getQueryInterface()
+            .showAllTables()
+            .then((tables) => tables.includes(versionTableName));
+
+        if (!versionTableExists) {
+            logger.info('🆕 Creating model_versions table...');
+            await sequelize.getQueryInterface().createTable(versionTableName, {
+                model_name: {
+                    type: sequelize.Sequelize.STRING,
+                    primaryKey: true,
+                },
+                version_hash: {
+                    type: sequelize.Sequelize.STRING(10),
+                    allowNull: false,
+                },
+                updated_at: {
+                    type: sequelize.Sequelize.DATE,
+                    allowNull: false,
+                    defaultValue: sequelize.Sequelize.literal('CURRENT_TIMESTAMP'),
+                },
+            });
+        }
+
+        const dbVersions = await sequelize.query(`SELECT model_name, version_hash FROM ${versionTableName}`, {
+            type: sequelize.QueryTypes.SELECT,
+        });
+
+        const dbVersionsMap = new Map(dbVersions?.map((v) => [v.model_name, v.version_hash]) || []);
+        const allModels = Object.values(sequelize.models);
+        const modelsToSync = [];
+        const changedModels = [];
+
+        for (const model of allModels) {
+            const newHash = generateModelHash(model);
+            const currentHash = dbVersionsMap.get(model.name);
+
+            if (newHash !== currentHash) {
+                const safe = await checkForDestructiveChanges(model, sequelize, logger, config);
+                if (!safe) {
+                    logger.error(`❌ Aborting sync due to destructive changes in ${model.name}`);
+                    process.exit(1);
+                }
+                modelsToSync.push({ model, newHash });
+                changedModels.push(model.name);
+            }
+        }
+
+        if (modelsToSync.length > 0) {
+            logger.info(`🔄 ${changedModels.length} models need sync: ${changedModels.join(', ')}`);
+
+            if (isProduction && !options.force) {
+                const proceed = await askForProductionSyncConfirmation(changedModels, logger);
+                if (!proceed) {
+                    process.exit(1);
+                }
+            }
+
+            for (const { model, newHash } of modelsToSync) {
+                logger.info(`🔄 Syncing model: ${model.name}...`);
+                await model.sync({ alter: true });
+
+                await sequelize.query(
+                    `INSERT INTO ${versionTableName} (model_name, version_hash, updated_at) 
+                        VALUES (?, ?, CURRENT_TIMESTAMP) 
+                        ON DUPLICATE KEY UPDATE 
+                        version_hash = VALUES(version_hash), updated_at = CURRENT_TIMESTAMP`,
+                    {
+                        replacements: [model.name, newHash],
+                        type: sequelize.QueryTypes.INSERT,
+                    }
+                );
+
+                logger.info(`✅ Synced model: ${model.name} (${newHash})`);
+            }
+
+            logger.info('✨ Database sync completed successfully!');
+        } else {
+            logger.info('💾 All model schemas are up to date.');
+        }
+
+        return sequelize;
+    } catch (err) {
+        logger.error('❌ Error during database sync:', err);
+        throw err;
+    }
+}
+
+module.exports = KythiaORM;

package/src/database/KythiaSequelize.js

@@ -0,0 +1,94 @@
+/**
+ * 🧠 Sequelize Connection Factory
+ *
+ * @file src/database/KythiaSequelize.js
+ * @copyright © 2025 kenndeclouv
+ * @assistant chaa & graa
+ * @version 0.9.3-beta
+ *
+ * @description
+ * Main Sequelize connection factory for the application
+ */
+const { Sequelize } = require('sequelize');
+
+/**
+ * 🧩 Creates and returns a Sequelize instance.
+ *
+ * @function createSequelizeInstance
+ * @param {object} config - The configuration object
+ * @param {object} logger - The logger instance
+ * @returns {Sequelize} Configured Sequelize instance
+ */
+function createSequelizeInstance(config, logger) {
+    const dbConfig = config.db || {};
+
+    const dialect = dbConfig.driver || process.env.DB_DRIVER;
+    const dbName = dbConfig.name || process.env.DB_NAME;
+    const dbUser = dbConfig.user || process.env.DB_USER;
+    const dbPassword = dbConfig.password || process.env.DB_PASSWORD;
+    const dbHost = dbConfig.host || process.env.DB_HOST;
+    const dbPort = dbConfig.port || process.env.DB_PORT;
+    const dbStorage = dbConfig.storagePath || process.env.DB_STORAGE_PATH;
+    const dbSocket = dbConfig.socketPath || process.env.DB_SOCKET_PATH;
+    const dbSsl = dbConfig.ssl || process.env.DB_SSL;
+    const dbDialectOptions = dbConfig.dialectOptions || process.env.DB_DIALECT_OPTIONS;
+
+    const seqConfig = {
+        database: dbName,
+        username: dbUser,
+        password: dbPassword,
+        dialect: dialect,
+        logging: (sql) => {
+            logger.debug(sql);
+        },
+        define: {
+            charset: 'utf8mb4',
+            collate: 'utf8mb4_unicode_ci',
+        },
+        timezone: dbConfig.timezone || '+00:00',
+    };
+
+    switch (dialect) {
+        case 'sqlite':
+            seqConfig.storage = dbStorage;
+            break;
+
+        case 'mysql':
+        case 'mariadb':
+            seqConfig.host = dbHost;
+            seqConfig.port = dbPort;
+            if (dbSocket) {
+                seqConfig.dialectOptions = { socketPath: dbSocket };
+            }
+            break;
+
+        case 'postgres':
+            seqConfig.host = dbHost;
+            seqConfig.port = dbPort;
+            if (dbSsl === 'true' || dbSsl === true) {
+                seqConfig.dialectOptions = {
+                    ssl: { require: true, rejectUnauthorized: false },
+                };
+            }
+            break;
+
+        case 'mssql':
+            seqConfig.host = dbHost;
+            seqConfig.port = dbPort;
+            if (dbDialectOptions) {
+                try {
+                    seqConfig.dialectOptions = typeof dbDialectOptions === 'string' ? JSON.parse(dbDialectOptions) : dbDialectOptions;
+                } catch (e) {
+                    logger.error('Error parsing dialect options:', e.message);
+                }
+            }
+            break;
+
+        default:
+            throw new Error(`${dialect} is not supported or not configured.`);
+    }
+
+    return new Sequelize(seqConfig);
+}
+
+module.exports = createSequelizeInstance;