kythia-core 0.9.5-beta → 0.11.0-beta

package/README.md

@@ -289,10 +289,105 @@ module.exports = {
 
 -----
 
-## 🗄️ Database Layer (`KythiaModel` & `KythiaORM`)
+## 🗄️ Database Layer (`KythiaModel` & Migrations)
 
-  * **`KythiaModel`:** Provides a robust caching layer out-of-the-box. Extend it for all your models. Remember to call `KythiaModel.setDependencies` once. The hybrid Redis/Map cache ensures performance and resilience. Tag-based invalidation keeps caches fresh with precision.
-  * **`KythiaORM`:** Handles database synchronization safely. It only alters tables when necessary, preventing accidental data loss in production and speeding up development startup. Ensure all models extend `KythiaModel` and have a `static init(sequelize)` method for `KythiaORM` to discover and initialize them correctly.
+The core abandons traditional `sync()` operations in favor of a robust, **Laravel-style migration system** combined with **Database Introspection**.
+
+### 1. `KythiaModel` (The Base Model)
+* **Hybrid Caching:** Provides a zero-config caching layer. It prioritizes **Redis** for distributed caching and falls back to a local **LRU Map** if Redis is unreachable (Shard Mode aware).
+* **Auto-Boot Introspection:** You don't need to define attributes manually in your model classes. The `autoBoot` method automatically introspects the database table schema to define Sequelize attributes at runtime.
+* **Smart Invalidation:** Includes `afterSave`, `afterDestroy`, and `afterBulk` hooks that automatically invalidate cache entries using **tag-based sniper invalidation** (e.g., clearing `User:ID:1` also clears related queries).
+
+### 2. `KythiaMigrator` (Migration Engine)
+* **Addon Scanning:** Automatically discovers migration files located in `addons/*/database/migrations`.
+* **Laravel-Style Batching:** Uses a custom `LaravelStorage` adapter for Umzug. It tracks migration **batches** (not just files), allowing you to rollback the entire last deployment (batch) rather than one file at a time.
+* **Production Safe:** Schema changes are strictly handled via migration files, eliminating the risk of accidental data loss caused by `sequelize.sync({ alter: true })` in production environments.
+
+-----
+
+## �️ 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.
 
 -----
 
@@ -304,4 +399,4 @@ module.exports = {
 
 ## 📜 License
 
-This project is licensed under the CC BY NC 4.0 License - see the [LICENSE](./LICENSE) file for details.
+This project is licensed under the CC BY NC 4.0 License - see the [LICENSE](./LICENSE) file for details.

package/changelog.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.9.6-beta](https://github.com/kenndeclouv/kythia-core/compare/v0.9.5-beta...v0.9.6-beta) (2025-11-18)
+
+
+### ✨ Added
+
+* Enhance KythiaModel with Redis scheduling methods for adding, removing, and retrieving expired items, improving cache management and scheduling capabilities. ([b98160a](https://github.com/kenndeclouv/kythia-core/commit/b98160abfa8396e06b432c91740c62c8f3a9e084))
+
 ### [0.9.5-beta](https://github.com/kenndeclouv/kythia-core/compare/v0.9.4-beta.3...v0.9.5-beta) (2025-11-11)
 
 

package/index.js

@@ -10,8 +10,6 @@ module.exports.KythiaModel = require('./src/database/KythiaModel.js');
 
 module.exports.createSequelizeInstance = require('./src/database/KythiaSequelize.js');
 
-module.exports.KythiaORM = require('./src/database/KythiaORM.js');
-
 module.exports.utils = require('./src/utils/index.js');
 
-module.exports.BaseCommand = require('./src/structures/BaseCommand.js')
+module.exports.BaseCommand = require('./src/structures/BaseCommand.js');

package/package.json

@@ -1,46 +1,69 @@
 {
-    "name": "kythia-core",
-    "version": "0.9.5-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": {
-        "test": "echo \"Error: no test specified\" && exit 1"
-    },
-    "keywords": [
-        "kythia",
-        "discord",
-        "bot",
-        "core",
-        "framework",
-        "addon",
-        "commands",
-        "components",
-        "extensible",
-        "modular"
-    ],
-    "author": {
-        "name": "kenndeclouv",
-        "mail": "kenndeclouv@gmail.com"
-    },
-    "license": "CC BY NC 4.0",
-    "type": "commonjs",
-    "dependencies": {
-        "@sentry/node": "^10.10.0",
-        "async-exit-hook": "^2.0.1",
-        "async-mutex": "^0.5.0",
-        "cli-color": "^2.0.4",
-        "dotenv": "^16.6.1",
-        "figlet": "^1.9.3",
-        "ioredis": "^5.7.0",
-        "json-stable-stringify": "^1.3.0",
-        "lru-cache": "^11.2.2",
-        "sequelize": "^6.37.7"
-    },
-    "peerDependencies": {
-        "discord.js": "^14.22.1"
-    },
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/kenndeclouv/kythia-core.git"
-    }
+	"name": "kythia-core",
+	"version": "0.11.0-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": {
+		"format": "biome format --write .",
+		"fix": "biome check --write .",
+		"prepare": "husky"
+	},
+	"lint-staged": {
+		"*.{js,json}": [
+			"biome check --write --no-errors-on-unmatched"
+		]
+	},
+	"bin": {
+		"kythia": "./src/cli/index.js"
+	},
+	"keywords": [
+		"kythia",
+		"discord",
+		"bot",
+		"core",
+		"framework",
+		"addon",
+		"commands",
+		"components",
+		"extensible",
+		"modular"
+	],
+	"author": {
+		"name": "kenndeclouv",
+		"email": "kenndeclouv@gmail.com"
+	},
+	"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"
+	},
+	"peerDependencies": {
+		"discord.js": "^14.22.1"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/kenndeclouv/kythia-core.git"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.7",
+		"husky": "^9.1.7",
+		"lint-staged": "^16.2.7"
+	}
 }