kythia-core 0.10.1-beta → 0.11.1-beta

package/src/cli/utils/db.js

@@ -0,0 +1,117 @@
+/**
+ * 🔌 CLI Database & Migration Bootstrapper
+ *
+ * @file src/cli/utils/db.js
+ * @copyright © 2025 kenndeclouv
+ * @assistant chaa & graa
+ * @version 0.11.1-beta
+ *
+ * @description
+ * Initializes the database connection and migration engine (Umzug) specifically
+ * for CLI operations. It dynamically loads the project configuration and
+ * discovers migration files across all addons.
+ *
+ * ✨ Core Features:
+ * -  Dynamic Config: Loads `kythia.config.js` from the user's project root.
+ * -  Auto-Discovery: Scans `addons` directory for migration files.
+ * -  Pretty Logging: Custom console output using `picocolors` for migration status.
+ * -  Singleton-like: Exports shared instances of Sequelize and Umzug.
+ */
+
+require('@dotenvx/dotenvx/config');
+const fs = require('node:fs');
+const path = require('node:path');
+const { Umzug } = require('umzug');
+const createSequelizeInstance = require('../../database/KythiaSequelize');
+const KythiaStorage = require('../../database/KythiaStorage');
+const pc = require('picocolors');
+
+const configPath = path.resolve(process.cwd(), 'kythia.config.js');
+
+if (!fs.existsSync(configPath)) {
+	console.error('❌ kythia.config.js not found in root directory!');
+	process.exit(1);
+}
+
+const config = require(configPath);
+
+const logger = {
+	info: () => {},
+	error: console.error,
+	debug: () => {},
+};
+
+const sequelize = createSequelizeInstance(config, logger);
+
+function getMigrationFiles() {
+	const rootDir = process.cwd();
+	const addonsDir = path.join(rootDir, 'addons');
+
+	if (!fs.existsSync(addonsDir)) return [];
+
+	const migrationFiles = [];
+	const addonFolders = fs
+		.readdirSync(addonsDir)
+		.filter((f) => fs.statSync(path.join(addonsDir, f)).isDirectory());
+
+	for (const addon of addonFolders) {
+		const migrationDir = path.join(addonsDir, addon, 'database', 'migrations');
+		if (fs.existsSync(migrationDir)) {
+			const files = fs
+				.readdirSync(migrationDir)
+				.filter((f) => f.endsWith('.js'))
+				.map((f) => ({
+					name: f,
+					path: path.join(migrationDir, f),
+				}));
+			migrationFiles.push(...files);
+		}
+	}
+	return migrationFiles.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+const storage = new KythiaStorage({ sequelize });
+
+const umzugLogger = {
+	info: (event) => {
+		if (typeof event === 'object') {
+			if (event.event === 'migrated') {
+				console.log(
+					pc.green(`✅ Migrated:  ${event.name} `) +
+						pc.gray(`(${event.durationSeconds}s)`),
+				);
+			} else if (event.event === 'reverting') {
+				console.log(pc.yellow(`↩️ Reverting: ${event.name}`));
+			} else if (event.event === 'reverted') {
+				console.log(
+					pc.red(`❌ Reverted:  ${event.name} `) +
+						pc.gray(`(${event.durationSeconds}s)`),
+				);
+			}
+		} else {
+			console.log(pc.dim(event));
+		}
+	},
+	warn: (msg) => console.warn(pc.yellow(`⚠️ ${msg}`)),
+	error: (msg) => console.error(pc.red(`🔥 ${msg}`)),
+};
+
+const umzug = new Umzug({
+	migrations: getMigrationFiles().map((m) => ({
+		name: m.name,
+		path: m.path,
+		up: async ({ context }) => {
+			const migration = require(m.path);
+			return migration.up(context, require('sequelize').DataTypes);
+		},
+		down: async ({ context }) => {
+			const migration = require(m.path);
+			return migration.down(context, require('sequelize').DataTypes);
+		},
+	})),
+	context: sequelize.getQueryInterface(),
+	storage: storage,
+	logger: umzugLogger,
+});
+
+module.exports = { sequelize, umzug, storage };

package/src/database/KythiaMigrator.js

@@ -4,7 +4,7 @@
  * @file src/database/KythiaMigrator.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.10.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.10.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Caching layer for Sequelize Models, now sharding-aware. When config.db.redis.shard === true,
@@ -32,7 +32,7 @@ const REDIS_ERROR_TOLERANCE_INTERVAL_MS = 10 * 1000;
 
 function safeStringify(obj, logger) {
 	try {
-		return JSON.stringify(obj, (value) =>
+		return JSON.stringify(obj, (_key, value) =>
 			typeof value === 'bigint' ? value.toString() : value,
 		);
 	} catch (err) {
@@ -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);
 			}
@@ -799,42 +829,43 @@ class KythiaModel extends Model {
 		}
 	}
 
-	/**
-	 * 🔴 (Private) Retrieves and deserializes an entry specifically from Redis.
-	 */
 	static async _redisGetCachedEntry(cacheKey, includeOptions) {
 		try {
 			const result = await this.redis.get(cacheKey);
+
 			if (result === null || result === undefined)
 				return { hit: false, data: undefined };
 
 			this.cacheStats.redisHits++;
-			if (result === NEGATIVE_CACHE_PLACEHOLDER)
+			if (result === NEGATIVE_CACHE_PLACEHOLDER) {
 				return { hit: true, data: null };
+			}
 
 			const parsedData = safeParse(result, this.logger);
 
-			if (typeof parsedData !== 'object' || parsedData === null) {
-				return { hit: true, data: parsedData };
+			if (parsedData === null) {
+				return { hit: false, data: undefined };
 			}
 
 			const includeAsArray = includeOptions
 				? 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) {
@@ -1056,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]) } });
@@ -1075,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;
 		}
@@ -1095,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)
@@ -1105,7 +1132,7 @@ class KythiaModel extends Model {
 							}`,
 						);
 
-					this.setCacheEntry(cacheKey, record, ttl, tags);
+					await this.setCacheEntry(cacheKey, record, ttl, tags);
 				}
 				return record;
 			})
@@ -1143,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;
 			})
@@ -1341,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;
 	}
 
@@ -1414,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);
@@ -1434,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.10.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.10.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.10.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.10.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * Handles all addon loading, command registration, and component management.
@@ -466,6 +466,7 @@ class AddonManager {
 	async _loadTopLevelCommandGroup(
 		commandsPath,
 		addon,
+		addonPermissionDefaults,
 		commandNamesSet,
 		commandDataForDeployment,
 	) {
@@ -476,6 +477,14 @@ class AddonManager {
 			commandDef = this._instantiateBaseCommand(commandDef);
 		}
 
+		const category = addon.name;
+		const categoryDefaults = addonPermissionDefaults[category] || {};
+
+		commandDef = {
+			...categoryDefaults,
+			...commandDef,
+		};
+
 		const mainBuilder = this._createBuilderFromData(
 			commandDef.data,
 			SlashCommandBuilder,

package/src/managers/EventManager.js

@@ -4,7 +4,7 @@
  * @file src/managers/EventManager.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.10.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.10.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
@@ -763,7 +817,7 @@ class InteractionManager {
 							.setLabel(
 								await this.t(interaction, 'common.error.button.contact.owner'),
 							)
-							.setURL(`discord://-/users/${ownerFirstId}`),
+							.setURL(`https://discord.com/users/${ownerFirstId}`),
 					),
 				),
 		];

package/src/managers/ShutdownManager.js

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

package/.husky/pre-commit

@@ -1,4 +0,0 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
-npx lint-staged

package/biome.json

@@ -1,40 +0,0 @@
-{
-	"$schema": "https://biomejs.dev/schemas/2.3.7/schema.json",
-	"vcs": {
-		"enabled": true,
-		"clientKind": "git",
-		"useIgnoreFile": true
-	},
-	"files": {
-		"ignoreUnknown": false
-	},
-	"formatter": {
-		"enabled": true,
-		"indentStyle": "tab"
-	},
-	"linter": {
-		"enabled": true,
-		"rules": {
-			"recommended": true,
-			"correctness": {
-				"noUnusedVariables": "error"
-			},
-			"complexity": {
-				"noThisInStatic": "off"
-			}
-		}
-	},
-	"javascript": {
-		"formatter": {
-			"quoteStyle": "single"
-		}
-	},
-	"assist": {
-		"enabled": true,
-		"actions": {
-			"source": {
-				"organizeImports": "off"
-			}
-		}
-	}
-}