kythia-core 0.10.1-beta → 0.11.0-beta

package/src/cli/index.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+/**
+ * ⚡ Kythia CLI Entry Point
+ *
+ * @file src/cli/index.js
+ * @copyright © 2025 kenndeclouv
+ * @assistant chaa & graa
+ * @version 0.11.0-beta
+ *
+ * @description
+ * The main bootstrap entry point for the Kythia CLI.
+ * It dynamically scans, loads, and registers all command classes found in the
+ * `commands` directory, orchestrating the `commander` program execution.
+ *
+ * ✨ Core Features:
+ * -  Dynamic Loading: Automatically finds new commands without manual import.
+ * -  Class-Based Architecture: Supports standard `Command` class structure.
+ * -  Error Handling: Gracefully handles malformed commands during boot.
+ */
+
+const { version } = require('../../package.json');
+const { Command } = require('commander');
+const BaseCommand = require('./Command');
+const path = require('node:path');
+const pc = require('picocolors');
+const fs = require('node:fs');
+
+const program = new Command();
+
+program
+	.name('kythia')
+	.description(pc.cyan('🌸 Kythia Framework CLI'))
+	.version(version);
+
+const commandsDir = path.join(__dirname, 'commands');
+
+if (fs.existsSync(commandsDir)) {
+	const commandFiles = fs
+		.readdirSync(commandsDir)
+		.filter((file) => file.endsWith('.js'));
+
+	for (const file of commandFiles) {
+		const filePath = path.join(commandsDir, file);
+		try {
+			const CommandClass = require(filePath);
+
+			if (
+				typeof CommandClass === 'function' &&
+				CommandClass.prototype instanceof BaseCommand
+			) {
+				const commandInstance = new CommandClass();
+				commandInstance.register(program);
+			} else if (typeof CommandClass.register === 'function') {
+				CommandClass.register(program);
+			} else {
+				console.warn(
+					pc.yellow(
+						`⚠️  Skipped ${file}: Not a valid Command class or missing 'register' function.`,
+					),
+				);
+			}
+		} catch (err) {
+			console.error(pc.red(`❌ Failed to load command ${file}:`), err);
+		}
+	}
+}
+
+program.parse(process.argv);

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.0-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.0-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.0-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) {
@@ -799,23 +799,22 @@ 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

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.0-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.0-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.0-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.0-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.0-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.0-beta
  *
  * @description
  * Handles all Discord interaction events including slash commands, buttons, modals,
@@ -763,7 +763,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.0-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"
-			}
-		}
-	}
-}