kythia-core 0.10.1-beta → 0.11.1-beta

package/README.md

@@ -305,6 +305,92 @@ The core abandons traditional `sync()` operations in favor of a robust, **Larave
 
 -----
 
+## �️ CLI Tools & Commands
+
+Kythia Core comes with a powerful CLI to streamline development, database management, and localization tasks.
+
+Run `npx kythia --help` to see all available commands.
+
+### Database Management
+
+#### `migrate`
+Run pending database migrations.
+```bash
+npx kythia migrate
+```
+**Options:**
+*   `-f, --fresh`: **[DANGER]** Wipe the entire database (drop all tables) and re-run all migrations from scratch.
+*   `-r, --rollback`: Rollback the last *batch* of migrations.
+
+#### `make:migration`
+Create a new timestamped migration file in an addon.
+```bash
+npx kythia make:migration --name create_users_table --addon core
+```
+**Options:**
+*   `--name <string>`: Name of the migration (snake_case recommended).
+*   `--addon <string>`: Target addon name (must exist in `addons/`).
+
+#### `make:model`
+Scaffold a new Sequelize model file in an addon.
+```bash
+npx kythia make:model --name User --addon core
+```
+**Options:**
+*   `--name <string>`: Name of the model (PascalCase recommended).
+*   `--addon <string>`: Target addon name.
+
+#### `cache:clear`
+Flush Redis cache. Supports multi-instance selection if `REDIS_URLS` is configured.
+```bash
+npx kythia cache:clear
+```
+
+### Localization (i18n)
+
+#### `lang:check`
+Lint translation key usage in your code against your language files.
+```bash
+npx kythia lang:check
+```
+*   **Static Analysis:** Uses AST parsing to find `t('key')` calls.
+*   **Validation:** Reports missing keys in JSON files.
+*   **Unused Keys:** Reports keys defined in `en.json` but never used in code.
+
+#### `lang:translate`
+Auto-translate your `en.json` to a target language using Google Gemini AI.
+```bash
+npx kythia lang:translate --target ja
+```
+**Options:**
+*   `--target <lang>`: Target language code (default: `ja`).
+*   **Requires:** `GEMINI_API_KEYS` in `.env`.
+
+### Development Utilities
+
+#### `dev:namespace`
+Automatically add or update JSDoc `@namespace` headers in all project files.
+```bash
+npx kythia dev:namespace
+```
+Useful for maintaining consistent file documentation and ownership headers.
+
+#### `gen:structure`
+Generate a markdown tree representation of your project structure.
+```bash
+npx kythia gen:structure
+```
+Outputs to `temp/structure.md`. Great for documentation or sharing context with AI.
+
+#### `version:up`
+Synchronize JSDoc `@version` tags across the project with `package.json`.
+```bash
+npx kythia version:up
+```
+Run this after bumping your package version to keep file headers in sync.
+
+-----
+
 ## 🔗 Peer Dependencies
 
   * **`discord.js`:** This is a `peerDependency`. `kythia-core` requires `discord.js` to function, but it expects the *consuming application* (your main bot) to provide it by listing `discord.js` in its own `dependencies`. This prevents version conflicts and issues with `instanceof` checks, especially common when using `npm link` during development. Ensure your main bot project has `discord.js` installed.
@@ -313,4 +399,4 @@ The core abandons traditional `sync()` operations in favor of a robust, **Larave
 
 ## 📜 License
 
-This project is licensed under the CC BY NC 4.0 License - see the [LICENSE](https://www.google.com/search?q=./LICENSE) file for details.
+This project is licensed under the CC BY NC 4.0 License - see the [LICENSE](./LICENSE) file for details.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kythia-core",
-	"version": "0.10.1-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": {
@@ -13,6 +13,9 @@
 			"biome check --write --no-errors-on-unmatched"
 		]
 	},
+	"bin": {
+		"kythia": "./src/cli/index.js"
+	},
 	"keywords": [
 		"kythia",
 		"discord",
@@ -32,15 +35,22 @@
 	"license": "CC BY NC 4.0",
 	"type": "commonjs",
 	"dependencies": {
+		"@babel/parser": "^7.28.5",
+		"@babel/traverse": "^7.28.5",
+		"@dotenvx/dotenvx": "^1.51.1",
+		"@google/genai": "^1.30.0",
 		"@sentry/node": "^10.10.0",
 		"async-exit-hook": "^2.0.1",
 		"async-mutex": "^0.5.0",
 		"cli-color": "^2.0.4",
+		"commander": "^14.0.2",
 		"dotenv": "^16.6.1",
 		"figlet": "^1.9.3",
+		"glob": "^13.0.0",
 		"ioredis": "^5.7.0",
 		"json-stable-stringify": "^1.3.0",
 		"lru-cache": "^11.2.2",
+		"picocolors": "^1.1.1",
 		"sequelize": "^6.37.7",
 		"umzug": "^3.8.2"
 	},

package/src/Kythia.js

@@ -4,7 +4,7 @@
  * @file src/Kythia.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.10.0-beta
+ * @version 0.11.1-beta
  *
  * @description
  * The heart of the application lifecycle. This class acts as the central
@@ -29,7 +29,9 @@ const AddonManager = require('./managers/AddonManager');
 const EventManager = require('./managers/EventManager');
 
 const KythiaMigrator = require('./database/KythiaMigrator');
-const ModelLoader = require('./database/ModelLoader');
+// const ModelLoader = require('./database/ModelLoader');
+const bootModels = require('./database/ModelLoader');
+const KythiaModel = require('./database/KythiaModel');
 
 class Kythia {
 	/**
@@ -380,7 +382,7 @@ class Kythia {
 				clc.cyan('Created by kenndeclouv'),
 				clc.cyan('Discord Support: ') + clc.underline('https://dsc.gg/kythia'),
 				clc.cyan('Official Documentation: ') +
-					clc.underline('https://kythia.my.id/commands'),
+					clc.underline('https://docs.kythia.me'),
 				'',
 				clc.cyanBright(`Kythia version: ${version}`),
 				'',
@@ -482,17 +484,17 @@ class Kythia {
 			this.logger.info('▬▬▬▬▬▬▬▬▬▬▬▬▬▬[ Connect Database ]▬▬▬▬▬▬▬▬▬▬▬▬▬▬');
 			await this.sequelize.authenticate();
 
-			this.logger.info('▬▬▬▬▬▬▬▬▬▬▬▬▬▬[ Run Migrations ]▬▬▬▬▬▬▬▬▬▬▬▬▬▬');
 			await KythiaMigrator({
 				sequelize: this.sequelize,
 				container: this.container,
 				logger: this.logger,
 			});
 
-			this.logger.info('▬▬▬▬▬▬▬▬▬▬▬▬▬▬[ Boot Models ]▬▬▬▬▬▬▬▬▬▬▬▬▬▬');
-			await ModelLoader(this, this.sequelize);
+			await bootModels(this, this.sequelize);
 
-			this.logger.info('🔄 Hydrating container with initialized models...');
+			this.logger.info('🪝 Attaching Cache Hooks...');
+
+			KythiaModel.attachHooksToAllModels(this.sequelize, this.client);
 
 			const handlers = this.addonManager.getHandlers();
 			this.eventManager = new EventManager({

package/src/KythiaClient.js

@@ -4,7 +4,7 @@
  * @file src/client/kythiaClient.js
  * @copyright © 2025 kenndeclouv
  * @assistant chaa & graa
- * @version 0.10.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

@@ -0,0 +1,68 @@
+/**
+ * 🏗️ Abstract Base Command
+ *
+ * @file src/cli/Command.js
+ * @copyright © 2025 kenndeclouv
+ * @assistant chaa & graa
+ * @version 0.11.1-beta
+ *
+ * @description
+ * The base class for all Kythia CLI commands. It enforces a standard structure
+ * (signature, description, handle) and manages the integration with Commander.js.
+ *
+ * ✨ Core Features:
+ * -  Standardized Interface: Enforces `handle()` implementation.
+ * -  Flexible Parsing: Handles both Options and Arguments intelligently.
+ * -  Auto Registration: Simplifies wiring commands to the main program.
+ */
+
+class Command {
+	/**
+	 * The name and signature of the console command.
+	 * @type {string}
+	 */
+	signature = '';
+
+	/**
+	 * The console command description.
+	 * @type {string}
+	 */
+	description = '';
+
+	/**
+	 * Execute the console command.
+	 * @param {Object} options - The options object from Commander
+	 * @param {...any} args - Positional arguments (if any)
+	 */
+	async handle(_options, ..._args) {
+		throw new Error('Command must implement handle method');
+	}
+
+	/**
+	 * Register the command with the program.
+	 * @param {import('commander').Command} program
+	 */
+	register(program) {
+		const cmd = program
+			.command(this.signature)
+			.description(this.description)
+			.action((...args) => {
+				const _commandObj = args.pop();
+				const opts = args.pop() || {};
+
+				this.handle(opts, ...args);
+			});
+
+		this.configure(cmd);
+	}
+
+	/**
+	 * Configure additional options or arguments.
+	 * @param {import('commander').Command} cmd
+	 */
+	configure(_cmd) {
+		// Override to add options
+	}
+}
+
+module.exports = Command;

package/src/cli/commands/CacheClearCommand.js

@@ -0,0 +1,136 @@
+/**
+ * 🧹 Redis Cache Flusher
+ *
+ * @file src/cli/commands/CacheClearCommand.js
+ * @copyright © 2025 kenndeclouv
+ * @assistant chaa & graa
+ * @version 0.11.1-beta
+ *
+ * @description
+ * Interactive utility to flush Redis cache. Supports intelligent handling of
+ * multiple Redis instances defined in environment variables.
+ *
+ * ✨ Core Features:
+ * -  Multi-Target: Detects and lists all Redis URLs from config.
+ * -  Safety First: Requires explicit confirmation before flushing.
+ * -  Target Selection: Allows flushing specific instances or all at once.
+ */
+
+const Command = require('../Command');
+const pc = require('picocolors');
+const readline = require('node:readline');
+const Redis = require('ioredis');
+require('@dotenvx/dotenvx/config');
+
+function askQuestion(query) {
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+	return new Promise((resolve) =>
+		rl.question(query, (ans) => {
+			rl.close();
+			resolve(ans);
+		}),
+	);
+}
+
+class CacheClearCommand extends Command {
+	signature = 'cache:clear';
+	description = 'Flush Redis cache (supports multi-instance selection)';
+
+	async handle() {
+		console.log(pc.dim('🔍 Detecting Redis configuration...'));
+
+		const redisUrlsRaw = process.env.REDIS_URLS;
+
+		if (!redisUrlsRaw) {
+			console.error(pc.red('❌ REDIS_URLS not found in .env'));
+			process.exit(1);
+		}
+
+		const urls = redisUrlsRaw
+			.split(',')
+			.map((u) => u.trim())
+			.filter((u) => u.length > 0);
+
+		if (urls.length === 0) {
+			console.error(pc.red('❌ No valid Redis URLs found.'));
+			process.exit(1);
+		}
+
+		let targets = [];
+
+		if (urls.length === 1) {
+			targets = [urls[0]];
+			console.log(pc.cyan(`🎯 Target: ${targets[0]}`));
+		} else {
+			console.log(
+				pc.yellow(`⚠️  Multiple Redis instances detected (${urls.length}):`),
+			);
+			console.log(
+				pc.dim('---------------------------------------------------'),
+			);
+			console.log(`0. ${pc.bgRed(pc.white(' FLUSH ALL INSTANCES '))}`);
+			urls.forEach((url, index) => {
+				const maskedUrl = url.replace(/:([^@]+)@/, ':****@');
+				console.log(`${index + 1}. ${maskedUrl}`);
+			});
+			console.log(
+				pc.dim('---------------------------------------------------'),
+			);
+
+			const answer = await askQuestion(
+				pc.cyan('Select target to flush (number): '),
+			);
+			const choice = parseInt(answer, 10);
+
+			if (Number.isNaN(choice) || choice < 0 || choice > urls.length) {
+				console.error(pc.red('❌ Invalid selection.'));
+				process.exit(1);
+			}
+
+			if (choice === 0) {
+				targets = urls;
+			} else {
+				targets = [urls[choice - 1]];
+			}
+		}
+
+		const confirm = await askQuestion(
+			pc.bgRed(pc.white(' DANGER ')) +
+				pc.yellow(
+					` Are you sure you want to FLUSHALL ${targets.length} instance(s)? (y/n): `,
+				),
+		);
+
+		if (confirm.toLowerCase() !== 'y' && confirm.toLowerCase() !== 'yes') {
+			console.log(pc.cyan('🛡️  Operation cancelled.'));
+			process.exit(0);
+		}
+
+		console.log('');
+		for (const url of targets) {
+			const masked = url.replace(/:([^@]+)@/, ':****@');
+			try {
+				console.log(pc.dim(`🔌 Connecting to ${masked}...`));
+				const redis = new Redis(url, {
+					maxRetriesPerRequest: 1,
+					retryStrategy: null,
+				});
+
+				await redis.flushall();
+				console.log(pc.green(`✅ FLUSHALL Success: ${masked}`));
+
+				redis.quit();
+			} catch (err) {
+				console.error(pc.red(`❌ Failed to flush ${masked}: ${err.message}`));
+			}
+		}
+
+		console.log(pc.green('\n✨ Cache clearing process completed.'));
+		process.exit(0);
+	}
+}
+
+module.exports = CacheClearCommand;