kythia-core 0.10.1-beta → 0.11.0-beta

package/src/cli/commands/MakeMigrationCommand.js

@@ -0,0 +1,82 @@
+/**
+ * 📐 Migration File Generator
+ *
+ * @file src/cli/commands/MakeMigrationCommand.js
+ * @copyright © 2025 kenndeclouv
+ * @assistant chaa & graa
+ * @version 0.11.0-beta
+ *
+ * @description
+ * Scaffolds a new database migration file with a precise YYYYMMDD_HHMMSS timestamp prefix.
+ * Places the file in the specified addon's migration directory.
+ *
+ * ✨ Core Features:
+ * -  Timestamped Ordering: Ensures migrations run in creation order.
+ * -  Addon Aware: Targets the correct module folder automatically.
+ * -  Template Injection: Provides standard up/down methods via `queryInterface`.
+ */
+
+const Command = require('../Command');
+const fs = require('node:fs');
+const path = require('node:path');
+const pc = require('picocolors');
+
+class MakeMigrationCommand extends Command {
+	signature = 'make:migration <name> <addon>';
+	description = 'Create a new migration file for an addon';
+
+	async handle(_options, name, addon) {
+		const rootDir = process.cwd();
+		const targetDir = path.join(
+			rootDir,
+			'addons',
+			addon,
+			'database',
+			'migrations',
+		);
+
+		if (!fs.existsSync(path.join(rootDir, 'addons', addon))) {
+			console.error(pc.red(`❌ Addon '${addon}' not found!`));
+			process.exit(1);
+		}
+
+		if (!fs.existsSync(targetDir)) {
+			fs.mkdirSync(targetDir, { recursive: true });
+		}
+
+		const now = new Date();
+		const timestamp = now
+			.toISOString()
+			.replace(/T/, '_')
+			.replace(/[-:]/g, '')
+			.split('.')[0];
+		const fileName = `${timestamp}_${name}.js`;
+		const filePath = path.join(targetDir, fileName);
+
+		const template = `/**
+ * @namespace: addons/${addon}/database/migrations/${fileName}
+ * @type: Database Migration
+ * @copyright © 2025 kenndeclouv
+ * @assistant chaa & graa
+ * @version 0.9.12-beta
+ */
+module.exports = {
+    async up(queryInterface, DataTypes) {
+        // await queryInterface.createTable('table_name', { 
+		// 		id: DataTypes.INTEGER 
+		// });
+    },
+
+    async down(queryInterface, DataTypes) {
+        // await queryInterface.dropTable('table_name');
+    }
+};`;
+
+		fs.writeFileSync(filePath, template);
+
+		console.log(pc.green('✅ Created migration:'));
+		console.log(pc.dim(`   addons/${addon}/database/migrations/${fileName}`));
+	}
+}
+
+module.exports = MakeMigrationCommand;

package/src/cli/commands/MakeModelCommand.js

@@ -0,0 +1,81 @@
+/**
+ * 📦 Model Scaffolding Tool
+ *
+ * @file src/cli/commands/MakeModelCommand.js
+ * @copyright © 2025 kenndeclouv
+ * @assistant chaa & graa
+ * @version 0.11.0-beta
+ *
+ * @description
+ * Generates new Sequelize model files extending `KythiaModel`.
+ * Automatically creates the directory structure and populates standard boilerplate.
+ *
+ * ✨ Core Features:
+ * -  Smart Scaffolding: Creates models in `addons/{addon}/database/models`.
+ * -  Duplicate Protection: Prevents overwriting existing models.
+ * -  Standard Boilerplate: Includes `guarded` and `structure` properties by default.
+ */
+
+const Command = require('../Command');
+const fs = require('node:fs');
+const path = require('node:path');
+const pc = require('picocolors');
+
+class MakeModelCommand extends Command {
+	signature = 'make:model <name> <addon>';
+	description = 'Create a new KythiaModel file';
+
+	async handle(_options, name, addon) {
+		//
+		const rootDir = process.cwd();
+		const targetDir = path.join(rootDir, 'addons', addon, 'database', 'models');
+
+		if (!fs.existsSync(path.join(rootDir, 'addons', addon))) {
+			console.error(pc.red(`❌ Addon '${addon}' not found!`));
+			process.exit(1);
+		}
+
+		if (!fs.existsSync(targetDir)) {
+			fs.mkdirSync(targetDir, { recursive: true });
+		}
+
+		const fileName = `${name}.js`;
+		const filePath = path.join(targetDir, fileName);
+
+		if (fs.existsSync(filePath)) {
+			console.error(
+				pc.red(`❌ Model '${fileName}' already exists in ${addon}!`),
+			);
+			process.exit(1);
+		}
+
+		const template = `/**
+ * @namespace: addons/${addon}/database/models/${fileName}
+ * @type: Database Model
+ * @copyright © ${new Date().getFullYear()} kenndeclouv
+ * @assistant chaa & graa
+ * @version 0.9.12-beta
+ */
+
+const { KythiaModel } = require("kythia-core");
+
+class ${name} extends KythiaModel {
+    static guarded = ["id"];
+
+    static get structure() {
+        return {
+            options: { timestamps: true },
+        };
+    }
+}
+
+module.exports = ${name};`;
+
+		fs.writeFileSync(filePath, template);
+
+		console.log(pc.green('✅ Created Model:'));
+		console.log(pc.dim(`   addons/${addon}/database/models/${fileName}`));
+	}
+}
+
+module.exports = MakeModelCommand;

package/src/cli/commands/MigrateCommand.js

@@ -0,0 +1,259 @@
+/**
+ * 🚜 Database Migration Runner
+ *
+ * @file src/cli/commands/MigrateCommand.js
+ * @copyright © 2025 kenndeclouv
+ * @assistant chaa & graa
+ * @version 0.11.0-beta
+ *
+ * @description
+ * Manages database schema updates using Umzug. Supports standard migration,
+ * fresh resets (nuclear option), and smart batch-based rollbacks.
+ *
+ * ✨ Core Features:
+ * -  Fresh Mode: Wipes database and re-runs migrations from scratch.
+ * -  Smart Rollback: Rolls back only the last batch of migrations.
+ * -  Auto-Create: Detects missing database and offers to create it.
+ * -  Safety Net: Prompts for confirmation on destructive actions.
+ */
+
+const Command = require('../Command');
+const { umzug, sequelize, storage } = require('../utils/db');
+const pc = require('picocolors');
+const readline = require('node:readline');
+
+function promptYN(question) {
+	return new Promise((resolve) => {
+		const rl = readline.createInterface({
+			input: process.stdin,
+			output: process.stdout,
+		});
+		rl.question(question, (answer) => {
+			rl.close();
+			resolve(answer.trim().toLowerCase());
+		});
+	});
+}
+
+class MigrateCommand extends Command {
+	signature = 'migrate';
+	description = 'Run pending database migrations';
+
+	configure(cmd) {
+		cmd
+			.option('-f, --fresh', 'Wipe database and re-run all migrations')
+			.option('-r, --rollback', 'Rollback the last batch of migrations');
+	}
+
+	async handle(options) {
+		console.log(pc.dim('🔌 Connecting to database...'));
+		let needReauth = false;
+
+		try {
+			await sequelize.authenticate();
+		} catch (err) {
+			const dbErrorCodes = ['ER_BAD_DB_ERROR', '3D000'];
+			if (
+				dbErrorCodes.includes(err.original?.code) ||
+				dbErrorCodes.includes(err.original?.sqlState)
+			) {
+				const dbName = sequelize.config?.database || '(unknown)';
+				console.log(pc.red(`❗ Database "${dbName}" does not exist.`));
+				const answer = await promptYN(
+					pc.yellow(`Do you want to create the database "${dbName}"? (y/n): `),
+				);
+				if (answer === 'y' || answer === 'yes') {
+					try {
+						const { Sequelize } = require('sequelize');
+						const currentDialect = sequelize.getDialect();
+						const adminConfig = {
+							...sequelize.config,
+							dialect: currentDialect,
+						};
+
+						if (currentDialect === 'mysql' || currentDialect === 'mariadb') {
+							delete adminConfig.database;
+						} else if (currentDialect === 'postgres') {
+							adminConfig.database = 'postgres';
+						} else if (currentDialect === 'sqlite') {
+							console.log(
+								pc.green('SQLite database file will be created automatically.'),
+							);
+						}
+
+						const adminSequelize = new Sequelize(adminConfig);
+						adminSequelize.options.logging = false;
+
+						await adminSequelize
+							.query(`CREATE DATABASE \`${dbName}\``)
+							.catch(async (e) => {
+								if (currentDialect === 'postgres') {
+									await adminSequelize.query(`CREATE DATABASE "${dbName}"`);
+								} else {
+									throw e;
+								}
+							});
+
+						await adminSequelize.close();
+						console.log(pc.green(`✅ Database "${dbName}" created.`));
+						needReauth = true;
+					} catch (createErr) {
+						console.error(
+							pc.bgRed(' ERROR '),
+							pc.red('Failed to create database:'),
+							createErr.message,
+						);
+						process.exit(1);
+					}
+				} else {
+					console.log(pc.red('Migration cancelled.'));
+					process.exit(1);
+				}
+			} else {
+				console.error(pc.bgRed(' ERROR '), pc.red(err.message));
+				process.exit(1);
+			}
+		}
+
+		if (needReauth) {
+			try {
+				await sequelize.authenticate();
+			} catch (e) {
+				console.error(
+					pc.bgRed(' ERROR '),
+					pc.red('Failed to connect after creating database:'),
+					e.message,
+				);
+				process.exit(1);
+			}
+		}
+
+		try {
+			if (options.fresh) {
+				console.log(pc.red('🧨 DROPPING ALL TABLES (Fresh)...'));
+
+				const answer = await promptYN(
+					pc.bgRed(pc.white(' DANGER ')) +
+						pc.yellow(' This will wipe ALL DATA. Are you sure? (y/n): '),
+				);
+				if (answer !== 'y' && answer !== 'yes') {
+					console.log(pc.cyan('Operation cancelled.'));
+					process.exit(0);
+				}
+
+				const queryInterface = sequelize.getQueryInterface();
+
+				if (
+					sequelize.getDialect() === 'mysql' ||
+					sequelize.getDialect() === 'mariadb'
+				) {
+					await sequelize.query('SET FOREIGN_KEY_CHECKS = 0', { raw: true });
+				} else if (sequelize.getDialect() === 'sqlite') {
+					await sequelize.query('PRAGMA foreign_keys = OFF', { raw: true });
+				}
+
+				try {
+					await queryInterface.dropAllTables();
+
+					await queryInterface.dropTable('migrations').catch(() => {});
+					await queryInterface.dropTable('SequelizeMeta').catch(() => {});
+
+					console.log(pc.green('✅ All tables dropped. Database is clean.'));
+				} catch (e) {
+					console.error(pc.red(`❌ Failed to drop tables: ${e.message}`));
+					throw e;
+				} finally {
+					if (
+						sequelize.getDialect() === 'mysql' ||
+						sequelize.getDialect() === 'mariadb'
+					) {
+						await sequelize.query('SET FOREIGN_KEY_CHECKS = 1', { raw: true });
+					} else if (sequelize.getDialect() === 'sqlite') {
+						await sequelize.query('PRAGMA foreign_keys = ON', { raw: true });
+					}
+				}
+
+				console.log(pc.dim('   -> Re-running all migrations...'));
+
+				if (storage && typeof storage.setBatch === 'function') {
+					storage.setBatch(1);
+				}
+
+				const executed = await umzug.up();
+
+				console.log(
+					pc.green(
+						`✅ Database refreshed! (${executed.length} migrations re-applied in Batch 1)`,
+					),
+				);
+				return;
+			}
+
+			if (options.rollback) {
+				const lastBatchNum = await storage.getLastBatchNumber();
+
+				if (lastBatchNum === 0) {
+					console.log(pc.gray('✨ Nothing to rollback (No batches found).'));
+					return;
+				}
+
+				const filesInBatch = await storage.getLastBatchMigrations();
+
+				console.log(
+					pc.yellow(
+						`⏪ Rolling back Batch #${lastBatchNum} (${filesInBatch.length} files)...`,
+					),
+				);
+
+				if (filesInBatch.length > 0) {
+					const rolledBack = await umzug.down({
+						migrations: filesInBatch,
+					});
+
+					if (rolledBack.length === 0)
+						console.log(
+							pc.red('❌ Rollback logic executed but no files processed.'),
+						);
+					else
+						console.log(
+							pc.green(`✅ Batch #${lastBatchNum} rolled back successfully.`),
+						);
+				} else {
+					console.log(
+						pc.gray(
+							'✨ Batch record exists but no files found (Manual DB modification?).',
+						),
+					);
+				}
+				return;
+			}
+
+			const pending = await umzug.pending();
+			if (pending.length === 0) {
+				console.log(pc.gray('✨ Nothing to migrate. Database is up to date.'));
+				return;
+			}
+
+			const lastBatch = await storage.getLastBatchNumber();
+			const newBatch = lastBatch + 1;
+
+			storage.setBatch(newBatch);
+
+			console.log(pc.cyan(`🚜 Running migrations (Batch #${newBatch})...`));
+
+			const executed = await umzug.up();
+
+			console.log(
+				pc.green(`✅ Batch #${newBatch} completed (${executed.length} files).`),
+			);
+		} catch (err) {
+			console.error(pc.bgRed(' ERROR '), pc.red(err.message));
+
+			process.exit(1);
+		} finally {
+			await sequelize.close();
+		}
+	}
+}
+
+module.exports = MigrateCommand;

package/src/cli/commands/NamespaceCommand.js

@@ -0,0 +1,112 @@
+/**
+ * 🏷️ JSDoc Namespace Automator
+ *
+ * @file src/cli/commands/NamespaceCommand.js
+ * @copyright © 2025 kenndeclouv
+ * @assistant chaa & graa
+ * @version 0.11.0-beta
+ *
+ * @description
+ * Scans the entire project structure and automatically adds or updates
+ * JSDoc `@namespace` headers to ensure code documentation consistency.
+ * Detects file types (Command, Model, Event) based on directory context.
+ *
+ * ✨ Core Features:
+ * -  Smart Detection: Infers `@type` from folder names (commands, events, etc).
+ * -  Recursive Scan: Processes nested directories including addons.
+ * -  Safe Update: Updates headers without touching code logic.
+ */
+
+const Command = require('../Command');
+const path = require('node:path');
+const pc = require('picocolors');
+const fs = require('node:fs');
+
+class NamespaceCommand extends Command {
+	signature = 'dev:namespace';
+	description = 'Add or update JSDoc @namespace headers in command files';
+
+	async handle() {
+		console.log(pc.cyan('🚀 Starting namespace annotation process...'));
+		const rootDir = process.cwd();
+
+		// Helper: Find Files Recursive
+		function findJsFilesRecursive(dir) {
+			let results = [];
+			if (!fs.existsSync(dir)) return results;
+			const list = fs.readdirSync(dir, { withFileTypes: true });
+			for (const file of list) {
+				if (file.name === 'node_modules' || file.name === '.git') continue;
+				const fullPath = path.join(dir, file.name);
+				if (file.isDirectory()) {
+					results = results.concat(findJsFilesRecursive(fullPath));
+				} else if (file.name.endsWith('.js')) {
+					results.push(fullPath);
+				}
+			}
+			return results;
+		}
+
+		function getFileType(filePath) {
+			const fileName = path.basename(filePath);
+			const parentDirName = path.basename(path.dirname(filePath));
+			const grandParentDirName = path.basename(
+				path.dirname(path.dirname(filePath)),
+			);
+
+			if (fileName === '_command.js') return 'Command Group Definition';
+			if (fileName === '_group.js') return 'Subcommand Group Definition';
+			if (parentDirName === 'commands' || grandParentDirName === 'commands')
+				return 'Command';
+			if (parentDirName === 'events') return 'Event Handler';
+			if (parentDirName === 'helpers') return 'Helper Script';
+			if (parentDirName === 'models') return 'Database Model';
+			if (parentDirName === 'migrations') return 'Database Migration';
+			if (parentDirName === 'tasks') return 'Scheduled Task';
+			return 'Module';
+		}
+
+		let filesToProcess = [];
+
+		const addonsPath = path.join(rootDir, 'addons');
+		if (fs.existsSync(addonsPath)) {
+			console.log(pc.dim('🔎 Scanning addons...'));
+			filesToProcess = filesToProcess.concat(findJsFilesRecursive(addonsPath));
+		}
+
+		const pkg = require(path.join(rootDir, 'package.json'));
+		const currentYear = new Date().getFullYear();
+
+		filesToProcess.forEach((filePath) => {
+			const relativePath = path.relative(rootDir, filePath).replace(/\\/g, '/');
+			const fileType = getFileType(filePath);
+
+			const newHeader = `/**
+ * @namespace: ${relativePath}
+ * @type: ${fileType}
+ * @copyright © ${currentYear} kenndeclouv
+ * @assistant chaa & graa
+ * @version ${pkg.version}
+ */`;
+
+			const content = fs.readFileSync(filePath, 'utf8');
+			const headerRegex = /\/\*\*[\s\S]*?namespace:[\s\S]*?\*\//;
+
+			let newContent;
+			if (headerRegex.test(content)) {
+				newContent = content.replace(headerRegex, newHeader.trim());
+			} else {
+				newContent = `${newHeader}\n\n${content}`;
+			}
+
+			if (newContent.trim() !== content.trim()) {
+				fs.writeFileSync(filePath, newContent, 'utf8');
+				console.log(pc.green(`🔄 Updated: ${relativePath}`));
+			}
+		});
+
+		console.log(pc.green('\n✅ Namespace annotation complete!'));
+	}
+}
+
+module.exports = NamespaceCommand;

package/src/cli/commands/StructureCommand.js

@@ -0,0 +1,70 @@
+/**
+ * 🗺️ Project Structure Mapper
+ *
+ * @file src/cli/commands/StructureCommand.js
+ * @copyright © 2025 kenndeclouv
+ * @assistant chaa & graa
+ * @version 0.11.0-beta
+ *
+ * @description
+ * Generates a markdown tree representation of the entire project directory.
+ * Useful for documentation and providing context to AI assistants.
+ *
+ * ✨ Core Features:
+ * -  Clean Output: Excludes noise (`node_modules`, `.git`).
+ * -  Format: Outputs standardized tree syntax to `temp/structure.md`.
+ */
+
+const Command = require('../Command');
+const fs = require('node:fs');
+const path = require('node:path');
+const pc = require('picocolors');
+
+class StructureCommand extends Command {
+	signature = 'gen:structure';
+	description = 'Generate project structure to temp/structure.md';
+
+	async handle() {
+		const rootDir = process.cwd();
+		const outputDir = path.join(rootDir, 'temp');
+		const outputFile = path.join(outputDir, 'structure.md');
+		const exclude = [
+			'.git',
+			'.vscode',
+			'node_modules',
+			'dist',
+			'logs',
+			'.husky',
+			'.yalc',
+		];
+
+		function generateTree(dir, prefix = '') {
+			const items = fs
+				.readdirSync(dir)
+				.filter((item) => !exclude.includes(item));
+			let tree = '';
+
+			items.forEach((item, index) => {
+				const fullPath = path.join(dir, item);
+				const isLast = index === items.length - 1;
+				const connector = isLast ? '└── ' : '├── ';
+				tree += `${prefix}${connector}${item}\n`;
+
+				if (fs.statSync(fullPath).isDirectory()) {
+					tree += generateTree(fullPath, prefix + (isLast ? '    ' : '│   '));
+				}
+			});
+			return tree;
+		}
+
+		if (!fs.existsSync(outputDir)) {
+			fs.mkdirSync(outputDir, { recursive: true });
+		}
+
+		const tree = generateTree(rootDir);
+		fs.writeFileSync(outputFile, tree, 'utf8');
+		console.log(pc.green(`✅ Project structure saved to: ${outputFile}`));
+	}
+}
+
+module.exports = StructureCommand;

package/src/cli/commands/UpversionCommand.js

@@ -0,0 +1,94 @@
+/**
+ * 🆙 Semantic Version Bumper
+ *
+ * @file src/cli/commands/UpversionCommand.js
+ * @copyright © 2025 kenndeclouv
+ * @assistant chaa & graa
+ * @version 0.11.0-beta
+ *
+ * @description
+ * Synchronizes the `@version` tag in all JSDoc headers across the project
+ * to match the version defined in `package.json`.
+ *
+ * ✨ Core Features:
+ * -  Mass Update: Updates hundreds of files in seconds.
+ * -  Regex Powered: Accurately targets version tags without affecting other code.
+ * -  Safety: Ignores sensitive folders like `node_modules` and `.git`.
+ */
+
+const Command = require('../Command');
+const fs = require('node:fs');
+const path = require('node:path');
+const pc = require('picocolors');
+
+class UpversionCommand extends Command {
+	signature = 'version:up';
+	description = 'Update @version in JSDoc headers to match package.json';
+
+	async handle() {
+		const rootDir = process.cwd();
+		const pkgPath = path.join(rootDir, 'package.json');
+
+		if (!fs.existsSync(pkgPath)) {
+			console.error(pc.red('❌ package.json not found!'));
+			process.exit(1);
+		}
+
+		const pkg = require(pkgPath);
+		const version = pkg.version;
+		console.log(pc.cyan(`✨ Using version from package.json: ${version}`));
+
+		const ignoredPaths = [
+			'node_modules',
+			'.git',
+			'.env',
+			'dist',
+			'obfuscate.js',
+			'.yalc',
+		];
+
+		function getAllJsFiles(dir, fileList = []) {
+			const files = fs.readdirSync(dir);
+			files.forEach((file) => {
+				const fullPath = path.join(dir, file);
+				if (ignoredPaths.includes(path.basename(fullPath))) return;
+
+				const stat = fs.statSync(fullPath);
+				if (stat.isDirectory()) {
+					getAllJsFiles(fullPath, fileList);
+				} else if (file.endsWith('.js')) {
+					fileList.push(fullPath);
+				}
+			});
+			return fileList;
+		}
+
+		const jsFiles = getAllJsFiles(rootDir);
+		const versionRegex = /(@version\s+)v?[\d.\-a-zA-Z]+/g;
+		let updatedCount = 0;
+
+		jsFiles.forEach((file) => {
+			try {
+				const originalContent = fs.readFileSync(file, 'utf8');
+				const newContent = originalContent.replace(
+					versionRegex,
+					`$1${version}`,
+				);
+
+				if (originalContent !== newContent) {
+					fs.writeFileSync(file, newContent, 'utf8');
+					console.log(pc.green(`✅ Updated: ${path.relative(rootDir, file)}`));
+					updatedCount++;
+				}
+			} catch (err) {
+				console.error(pc.red(`❌ Failed to process: ${file}`), err.message);
+			}
+		});
+
+		console.log(
+			pc.green(`\n🎉 Version update complete! (${updatedCount} files changed)`),
+		);
+	}
+}
+
+module.exports = UpversionCommand;