kythia-core 0.11.0-beta → 0.11.1-beta

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kythia-core",
-	"version": "0.11.0-beta",
+	"version": "0.11.1-beta",
 	"description": "Core library for the Kythia main Discord bot: extensible, modular, and scalable foundation for commands, components, and event management.",
 	"main": "index.js",
 	"scripts": {

package/src/Kythia.js

@@ -4,7 +4,7 @@
  * @file src/Kythia.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * The heart of the application lifecycle. This class acts as the central

package/src/KythiaClient.js

@@ -4,7 +4,7 @@
  * @file src/client/kythiaClient.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Factory function that initializes the Discord.js Client with high-performance
@@ -49,7 +49,6 @@ module.exports = function kythiaClient() {
 
 			ThreadManager: {
 				maxSize: 25,
-				keepOverLimit: (thread) => thread.isActive(),
 			},
 
 			GuildMemberManager: {

package/src/cli/Command.js

@@ -4,7 +4,7 @@
  * @file src/cli/Command.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * The base class for all Kythia CLI commands. It enforces a standard structure

package/src/cli/commands/CacheClearCommand.js

@@ -4,7 +4,7 @@
  * @file src/cli/commands/CacheClearCommand.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Interactive utility to flush Redis cache. Supports intelligent handling of

package/src/cli/commands/LangCheckCommand.js

@@ -4,7 +4,7 @@
  * @file src/cli/commands/LangCheckCommand.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Performs a deep AST analysis of the codebase to find `t()` translation function calls.
@@ -23,7 +23,25 @@ const glob = require('glob');
 const parser = require('@babel/parser');
 const traverse = require('@babel/traverse').default;
 
-function getAllKeys(obj, prefix = '') {
+function deepMerge(target, source) {
+	if (typeof target !== 'object' || target === null) return source;
+	if (typeof source !== 'object' || source === null) return source;
+
+	for (const key of Object.keys(source)) {
+		if (
+			source[key] instanceof Object &&
+			target[key] instanceof Object &&
+			!Array.isArray(source[key])
+		) {
+			target[key] = deepMerge(target[key], source[key]);
+		} else {
+			target[key] = source[key];
+		}
+	}
+	return target;
+}
+
+function getAllKeys(obj, allDefinedKeys, prefix = '') {
 	Object.keys(obj).forEach((key) => {
 		if (key === '_value' || key === 'text') {
 			if (Object.keys(obj).length === 1) return;
@@ -33,7 +51,7 @@ function getAllKeys(obj, prefix = '') {
 		const fullKey = prefix ? `${prefix}.${key}` : key;
 		if (typeof obj[key] === 'object' && obj[key] !== null) {
 			if (key !== 'jobs' && key !== 'shop') {
-				getAllKeys(obj[key], fullKey);
+				getAllKeys(obj[key], allDefinedKeys, fullKey);
 			} else {
 				allDefinedKeys.add(fullKey);
 			}
@@ -49,9 +67,8 @@ class LangCheckCommand extends Command {
 		'Lint translation key usage in code and language files (AST-based)';
 
 	async handle() {
-		const PROJECT_ROOT = path.join(__dirname, '..', '..', '..');
+		const PROJECT_ROOT = process.cwd();
 		const SCAN_DIRECTORIES = ['addons', 'src'];
-		const LANG_DIR = path.join(PROJECT_ROOT, 'src', 'lang');
 		const DEFAULT_LANG = 'en';
 		const IGNORE_PATTERNS = [
 			'**/node_modules/**',
@@ -94,41 +111,53 @@ class LangCheckCommand extends Command {
 		}
 
 		function _loadLocales() {
-			console.log(`\n🔍 Reading language files from: ${LANG_DIR}`);
+			console.log(`\n🔍 Searching for language files in: ${PROJECT_ROOT}`);
 			try {
-				const langFiles = fs
-					.readdirSync(LANG_DIR)
-					.filter(
-						(file) =>
-							file.endsWith('.json') &&
-							!file.includes('_flat') &&
-							!file.includes('_FLAT'),
-					);
+				const langFiles = glob.sync('**/lang/*.json', {
+					cwd: PROJECT_ROOT,
+					ignore: ['**/node_modules/**', '**/dist/**'],
+					absolute: true,
+				});
+
 				if (langFiles.length === 0) {
 					console.error(
 						'\x1b[31m%s\x1b[0m',
-						'❌ No .json files found in the language folder.',
+						'❌ No .json files found in any lang folder.',
 					);
 					return false;
 				}
+
+				let loadedCount = 0;
 				for (const file of langFiles) {
-					const lang = file.replace('.json', '');
-					const content = fs.readFileSync(path.join(LANG_DIR, file), 'utf8');
+					if (file.includes('_flat') || file.includes('_FLAT')) continue;
+
+					const filename = path.basename(file);
+					const lang = filename.replace('.json', '');
+					const content = fs.readFileSync(file, 'utf8');
+
 					try {
-						locales[lang] = JSON.parse(content);
-						console.log(`  > Successfully loaded: ${file}`);
+						const parsed = JSON.parse(content);
+						if (!locales[lang]) {
+							locales[lang] = parsed;
+						} else {
+							// Merge with existing locale data
+							locales[lang] = deepMerge(locales[lang], parsed);
+						}
+						loadedCount++;
 					} catch (jsonError) {
 						console.error(
 							`\x1b[31m%s\x1b[0m`,
-							`❌ Failed to parse JSON: ${file} - ${jsonError.message}`,
+							`❌ Failed to parse JSON: ${path.relative(PROJECT_ROOT, file)} - ${jsonError.message}`,
 						);
 						filesWithErrors++;
 					}
 				}
+				console.log(`  > Successfully loaded ${loadedCount} language files.`);
+
 				if (!locales[DEFAULT_LANG]) {
 					console.error(
 						`\x1b[31m%s\x1b[0m`,
-						`❌ Default language (${DEFAULT_LANG}) not found!`,
+						`❌ Default language (${DEFAULT_LANG}) not found in any loaded files!`,
 					);
 					return false;
 				}
@@ -303,7 +332,7 @@ class LangCheckCommand extends Command {
 
 		if (defaultLocale) {
 			try {
-				getAllKeys(defaultLocale);
+				getAllKeys(defaultLocale, allDefinedKeys);
 			} catch (e) {
 				console.error('Error collecting defined keys:', e);
 			}

package/src/cli/commands/LangTranslateCommand.js

@@ -4,7 +4,7 @@
  * @file src/cli/commands/LangTranslateCommand.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Automates the translation of the core language file (`en.json`) to a target language

package/src/cli/commands/MakeMigrationCommand.js

@@ -4,7 +4,7 @@
  * @file src/cli/commands/MakeMigrationCommand.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Scaffolds a new database migration file with a precise YYYYMMDD_HHMMSS timestamp prefix.

package/src/cli/commands/MakeModelCommand.js

@@ -4,7 +4,7 @@
  * @file src/cli/commands/MakeModelCommand.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Generates new Sequelize model files extending `KythiaModel`.

package/src/cli/commands/MigrateCommand.js

@@ -4,7 +4,7 @@
  * @file src/cli/commands/MigrateCommand.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Manages database schema updates using Umzug. Supports standard migration,

package/src/cli/commands/NamespaceCommand.js

@@ -4,7 +4,7 @@
  * @file src/cli/commands/NamespaceCommand.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Scans the entire project structure and automatically adds or updates

package/src/cli/commands/StructureCommand.js

@@ -4,7 +4,7 @@
  * @file src/cli/commands/StructureCommand.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Generates a markdown tree representation of the entire project directory.

package/src/cli/commands/UpversionCommand.js

@@ -4,7 +4,7 @@
  * @file src/cli/commands/UpversionCommand.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Synchronizes the `@version` tag in all JSDoc headers across the project

package/src/cli/index.js

@@ -6,7 +6,7 @@
  * @file src/cli/index.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * The main bootstrap entry point for the Kythia CLI.

package/src/cli/utils/db.js

@@ -4,7 +4,7 @@
  * @file src/cli/utils/db.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Initializes the database connection and migration engine (Umzug) specifically

package/src/database/KythiaMigrator.js

@@ -4,7 +4,7 @@
  * @file src/database/KythiaMigrator.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Scans 'addons' folder for migration files and executes them using Umzug.

package/src/database/KythiaModel.js

@@ -4,7 +4,7 @@
  * @file src/database/KythiaModel.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Caching layer for Sequelize Models, now sharding-aware. When config.db.redis.shard === true,
@@ -659,10 +659,6 @@ class KythiaModel extends Model {
 	 * @param {string|Object} queryIdentifier - A unique string or a Sequelize query object.
 	 * @returns {string} The final cache key, prefixed with the model's name (e.g., "User:{\"id\":1}").
 	 */
-	/**
-	 * 🔑 Generates a consistent, model-specific cache key from a query identifier.
-	 * FIXED: Handle BigInt in json-stable-stringify
-	 */
 	static getCacheKey(queryIdentifier) {
 		let dataToHash = queryIdentifier;
 
@@ -676,7 +672,7 @@ class KythiaModel extends Model {
 		}
 
 		const opts = {
-			replacer: (value) =>
+			replacer: (_key, value) =>
 				typeof value === 'bigint' ? value.toString() : value,
 		};
 
@@ -712,6 +708,38 @@ class KythiaModel extends Model {
 		return normalized;
 	}
 
+	/**
+	 * 🧠 Generate tags based on PK and static cacheKeys definition.
+	 * Used for smart invalidation (e.g. invalidate all items belonging to a userId).
+	 */
+	static _generateSmartTags(instance) {
+		if (!instance) return [`${this.name}`];
+
+		const tags = [`${this.name}`];
+
+		const pk = this.primaryKeyAttribute;
+		if (instance[pk]) {
+			tags.push(`${this.name}:${pk}:${instance[pk]}`);
+		}
+
+		const smartKeys = this.cacheKeys || this.CACHE_KEYS || [];
+
+		if (Array.isArray(smartKeys)) {
+			for (const keyGroup of smartKeys) {
+				const keys = Array.isArray(keyGroup) ? keyGroup : [keyGroup];
+				const hasAllValues = keys.every(
+					(k) => instance[k] !== undefined && instance[k] !== null,
+				);
+
+				if (hasAllValues) {
+					const tagParts = keys.map((k) => `${k}:${instance[k]}`).join(':');
+					tags.push(`${this.name}:${tagParts}`);
+				}
+			}
+		}
+		return tags;
+	}
+
 	/**
 	 * 📥 [HYBRID/SHARD ROUTER] Sets a value in the currently active cache engine.
 	 * In shard mode, if Redis down, nothing is cached.
@@ -774,6 +802,7 @@ class KythiaModel extends Model {
 	static async _redisSetCacheEntry(cacheKey, data, ttl, tags = []) {
 		try {
 			let plainData = data;
+
 			if (data && typeof data.toJSON === 'function') {
 				plainData = data.toJSON();
 			} else if (Array.isArray(data)) {
@@ -789,6 +818,7 @@ class KythiaModel extends Model {
 
 			const multi = this.redis.multi();
 			multi.set(cacheKey, valueToStore, 'PX', ttl);
+
 			for (const tag of tags) {
 				multi.sadd(tag, cacheKey);
 			}
@@ -821,19 +851,21 @@ class KythiaModel extends Model {
 				? Array.isArray(includeOptions)
 					? includeOptions
 					: [includeOptions]
-				: null;
+				: undefined;
 
-			if (Array.isArray(parsedData)) {
-				const instances = this.bulkBuild(parsedData, {
+			const buildInstance = (data) => {
+				const instance = this.build(data, {
 					isNewRecord: false,
 					include: includeAsArray,
 				});
+				return instance;
+			};
+
+			if (Array.isArray(parsedData)) {
+				const instances = parsedData.map((d) => buildInstance(d));
 				return { hit: true, data: instances };
 			} else {
-				const instance = this.build(parsedData, {
-					isNewRecord: false,
-					include: includeAsArray,
-				});
+				const instance = buildInstance(parsedData);
 				return { hit: true, data: instance };
 			}
 		} catch (err) {
@@ -1055,14 +1087,6 @@ class KythiaModel extends Model {
 	static async getCache(keys, options = {}) {
 		const { noCache, customCacheKey, ttl, ...explicitQueryOptions } = options;
 
-		if (noCache) {
-			const queryToRun = {
-				...this._normalizeFindOptions(keys),
-				...explicitQueryOptions,
-			};
-			return this.findOne(queryToRun);
-		}
-
 		if (Array.isArray(keys)) {
 			const pk = this.primaryKeyAttribute;
 			return this.findAll({ where: { [pk]: keys.map((m) => m[pk]) } });
@@ -1074,11 +1098,15 @@ class KythiaModel extends Model {
 			...normalizedKeys,
 			...explicitQueryOptions,
 			where: {
-				...normalizedKeys.where,
+				...(normalizedKeys.where || {}),
 				...(explicitQueryOptions.where || {}),
 			},
 		};
 
+		if (noCache) {
+			return this.findOne(finalQuery);
+		}
+
 		if (!finalQuery.where || Object.keys(finalQuery.where).length === 0) {
 			return null;
 		}
@@ -1094,7 +1122,7 @@ class KythiaModel extends Model {
 			return this.pendingQueries.get(cacheKey);
 
 		const queryPromise = this.findOne(finalQuery)
-			.then((record) => {
+			.then(async (record) => {
 				if (this.isRedisConnected || !this.isShardMode) {
 					const tags = [`${this.name}`];
 					if (record)
@@ -1104,7 +1132,7 @@ class KythiaModel extends Model {
 							}`,
 						);
 
-					this.setCacheEntry(cacheKey, record, ttl, tags);
+					await this.setCacheEntry(cacheKey, record, ttl, tags);
 				}
 				return record;
 			})
@@ -1142,12 +1170,12 @@ class KythiaModel extends Model {
 			return this.pendingQueries.get(cacheKey);
 
 		const queryPromise = this.findAll(normalizedOptions)
-			.then((records) => {
+			.then(async (records) => {
 				if (this.isRedisConnected || !this.isShardMode) {
 					const tags = [`${this.name}`];
 					if (Array.isArray(cacheTags)) tags.push(...cacheTags);
 
-					this.setCacheEntry(cacheKey, records, ttl, tags);
+					await this.setCacheEntry(cacheKey, records, ttl, tags);
 				}
 				return records;
 			})
@@ -1340,29 +1368,40 @@ class KythiaModel extends Model {
 	}
 
 	/**
-	 * 📦 An instance method that saves the current model instance to the database and then
-	 * intelligently updates its corresponding entry in the active cache.
+	 * 📦 FIXED: Save data to DB, then INVALIDATE the cache tags.
+	 * Don't try to setCache here, because .save() result doesn't have associations/includes.
+	 * Let the next getCache() fetch the full fresh data tree.
 	 */
 	async saveAndUpdateCache() {
 		const savedInstance = await this.save();
 		const pk = this.constructor.primaryKeyAttribute;
 		const pkValue = this[pk];
+
 		if (
 			pkValue &&
 			(this.constructor.isRedisConnected || !this.constructor.isShardMode)
 		) {
-			const cacheKey = this.constructor.getCacheKey({ [pk]: pkValue });
+			const cacheKey = this.constructor.getCacheKey({
+				where: { [pk]: pkValue },
+			});
+
 			const tags = [
 				`${this.constructor.name}`,
 				`${this.constructor.name}:${pk}:${pkValue}`,
 			];
+
 			await this.constructor.setCacheEntry(
 				cacheKey,
 				savedInstance,
 				undefined,
 				tags,
 			);
+
+			this.constructor.logger.info(
+				`🔄 [CACHE] Updated cache for ${this.constructor.name}:${pk}:${pkValue}`,
+			);
 		}
+
 		return savedInstance;
 	}
 
@@ -1413,16 +1452,11 @@ class KythiaModel extends Model {
 			return;
 		}
 
-		/**
-		 * Logika setelah data disimpan (Create atau Update)
-		 */
 		const afterSaveLogic = async (instance) => {
 			const modelClass = instance.constructor;
 
 			if (modelClass.isRedisConnected) {
-				const tagsToInvalidate = [`${modelClass.name}`];
-				const pk = modelClass.primaryKeyAttribute;
-				tagsToInvalidate.push(`${modelClass.name}:${pk}:${instance[pk]}`);
+				const tagsToInvalidate = modelClass._generateSmartTags(instance);
 
 				if (Array.isArray(modelClass.customInvalidationTags)) {
 					tagsToInvalidate.push(...modelClass.customInvalidationTags);
@@ -1433,16 +1467,11 @@ class KythiaModel extends Model {
 			}
 		};
 
-		/**
-		 * Logika setelah data dihapus
-		 */
 		const afterDestroyLogic = async (instance) => {
 			const modelClass = instance.constructor;
 
 			if (modelClass.isRedisConnected) {
-				const tagsToInvalidate = [`${modelClass.name}`];
-				const pk = modelClass.primaryKeyAttribute;
-				tagsToInvalidate.push(`${modelClass.name}:${pk}:${instance[pk]}`);
+				const tagsToInvalidate = modelClass._generateSmartTags(instance);
 
 				if (Array.isArray(modelClass.customInvalidationTags)) {
 					tagsToInvalidate.push(...modelClass.customInvalidationTags);

package/src/database/KythiaSequelize.js

@@ -4,7 +4,7 @@
  * @file src/database/KythiaSequelize.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Main Sequelize connection factory for the application.

package/src/database/KythiaStorage.js

@@ -4,7 +4,7 @@
  * @file src/database/KythiaStorage.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Custom storage adapter for Umzug that mimics Laravel's migration table structure.

package/src/database/ModelLoader.js

@@ -4,7 +4,7 @@
  * @file src/loaders/ModelLoader.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Scans the `addons` directory for KythiaModel definitions, requires them,

package/src/managers/AddonManager.js

@@ -4,7 +4,7 @@
  * @file src/managers/AddonManager.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Handles all addon loading, command registration, and component management.

package/src/managers/EventManager.js

@@ -4,7 +4,7 @@
  * @file src/managers/EventManager.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Handles all Discord event listeners except InteractionCreate.

package/src/managers/InteractionManager.js

@@ -4,7 +4,7 @@
  * @file src/managers/InteractionManager.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Handles all Discord interaction events including slash commands, buttons, modals,
@@ -56,6 +56,10 @@ class InteractionManager {
 		this.KythiaVoter = this.models.KythiaVoter;
 		this.isTeam = this.helpers.discord.isTeam;
 		this.isOwner = this.helpers.discord.isOwner;
+
+		if (!this.client.restartNoticeCooldowns) {
+			this.client.restartNoticeCooldowns = new Collection();
+		}
 	}
 
 	/**
@@ -305,6 +309,8 @@ class InteractionManager {
 			} else {
 				await command.execute(interaction);
 			}
+
+			await this._checkRestartSchedule(interaction);
 		} else {
 			this.logger.error(
 				"Command doesn't have a valid 'execute' function:",
@@ -637,6 +643,9 @@ class InteractionManager {
 		if (this.container && !this.container.logger) {
 			this.container.logger = this.logger;
 		}
+
+		await this._checkRestartSchedule(interaction);
+
 		await command.execute(interaction, this.container);
 	}
 
@@ -706,6 +715,51 @@ class InteractionManager {
 		}
 	}
 
+	/**
+	 * Check for scheduled restart and notify user
+	 * @private
+	 */
+	async _checkRestartSchedule(interaction) {
+		const restartTs = this.client.kythiaRestartTimestamp;
+
+		if (!restartTs || interaction.commandName === 'restart') return;
+
+		const userId = interaction.user.id;
+		const cooldowns = this.client.restartNoticeCooldowns;
+		const now = Date.now();
+		const cooldownTime = 5 * 60 * 1000;
+
+		if (cooldowns.has(userId)) {
+			const lastNotified = cooldowns.get(userId);
+			if (now - lastNotified < cooldownTime) {
+				return;
+			}
+		}
+
+		const timeLeft = restartTs - now;
+
+		if (timeLeft > 0) {
+			try {
+				const timeString = `<t:${Math.floor(restartTs / 1000)}:R>`;
+				// TODO: Add translation
+				const msg = `## ⚠️ System Notice\nKythia is scheduled to restart **${timeString}**.`;
+
+				if (interaction.replied || interaction.deferred) {
+					await interaction.followUp({
+						content: msg,
+						flags: MessageFlags.Ephemeral,
+					});
+
+					cooldowns.set(userId, now);
+
+					setTimeout(() => cooldowns.delete(userId), cooldownTime);
+				}
+			} catch (err) {
+				this.logger.error(err);
+			}
+		}
+	}
+
 	/**
 	 * Handle interaction errors
 	 * @private

package/src/managers/ShutdownManager.js

@@ -4,7 +4,7 @@
  * @file src/managers/ShutdownManager.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.11.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Handles graceful shutdown procedures including interval tracking,