@joktec/skills 0.1.0

package/dist/cursor/.cursor/rules/joktec-framework-skill.mdc

@@ -0,0 +1,62 @@
+---
+description: Use when working in a consumer project that uses @joktec/* packages and the agent needs to choose the right JokTec package skill, understand package boundaries, wire modules, or avoid mixing app logic into reusable JokTec infrastructure.
+globs: **/*
+alwaysApply: false
+---
+
+# JokTec Framework Skill
+
+Start here when a task mentions JokTec generally, multiple `@joktec/*` packages, or a consumer app that needs framework wiring.
+
+## Select The Focused Skill
+
+- For `@joktec/core`, `@joktec/utils`, or `@joktec/cron`, use `joktec-common-skill`.
+- For `@joktec/mongo`, use `joktec-mongo-skill`.
+- For `@joktec/mysql`, use `joktec-mysql-skill`.
+- For Kafka, RabbitMQ, SQS, or Redcast, use `joktec-broker-skill`.
+- For cache, mail, notification, or storage adapters, use `joktec-adapter-skill`.
+- For Elastic, Arango, or BigQuery, use `joktec-database-extended-skill`.
+- For Firebase or GPT integrations, use `joktec-integration-skill`.
+- For HTTP, file, or alert utilities, use `joktec-tool-skill`.
+
+## Core Rules
+
+- Treat `joktec-framework` code, package README files, and agent docs as source-of-truth.
+- Keep consumer app business logic in the app; do not move it into `@joktec/*` packages.
+- Prefer config-driven module setup and `conId` when a package supports multiple clients.
+- Preserve NestJS module boundaries, dependency injection, lifecycle hooks, and exported package APIs.
+- Do not invent behavior for unfinished or missing packages.
+
+## Reference
+
+Read `references/framework-map.md` when the task needs package selection, dependency flow, or a quick map from requirement to package.
+
+## Bundled References
+
+### references/framework-map.md
+
+# JokTec Framework Map
+
+## Package Families
+
+- `@joktec/core`: bootstrap, config, logger, metrics, guards, base abstractions, transports, pagination, Bull.
+- `@joktec/utils`: low-level helpers, validators, conversion utilities.
+- `@joktec/cron`: cron decorators, schedulers, job workers.
+- `@joktec/mongo`: Mongoose/Typegoose database adapter and repository.
+- `@joktec/mysql`: TypeORM relational adapter and repository.
+- `@joktec/kafka`, `@joktec/rabbit`, `@joktec/sqs`, `@joktec/redcast`: broker clients and decorators.
+- `@joktec/cacher`, `@joktec/mailer`, `@joktec/notifier`, `@joktec/storage`: external capability adapters.
+- `@joktec/elastic`, `@joktec/arango`, `@joktec/bigquery`: extended database clients.
+- `@joktec/firebase`, `@joktec/gpt`: third-party integrations.
+- `@joktec/http`, `@joktec/file`, `@joktec/alert`: reusable tools.
+
+## Dependency Direction
+
+Consumer apps depend on concrete `@joktec/*` packages. Concrete packages usually depend on `@joktec/core` and `@joktec/utils`. Keep app-specific schemas, handlers, and business semantics outside reusable packages.
+
+## Common Consumer App Pattern
+
+1. Register package modules in the app module or repository module.
+2. Keep app schemas/entities and app repositories in the consumer app.
+3. Extend the package repository base class when the package provides one.
+4. Use `BaseService`, `BaseController`, or transport helpers from `@joktec/core` when the app follows standard CRUD or message patterns.

package/dist/cursor/.cursor/rules/joktec-integration-skill.mdc

@@ -0,0 +1,39 @@
+---
+description: Use when wiring or using JokTec integration packages @joktec/firebase or @joktec/gpt, including validated config, SDK client lifecycle, app-neutral integration services, credentials handling, and consumer app composition.
+globs: packages/integrations/**
+alwaysApply: false
+---
+
+# JokTec Integration Skill
+
+Use this skill for third-party integration packages.
+
+## Packages
+
+- `@joktec/firebase`: Firebase Admin SDK integration.
+- `@joktec/gpt`: GPT/OpenAI-style client integration.
+
+## Rules
+
+- Keep credentials config-driven and never commit real credentials.
+- Use package services instead of direct SDK initialization in app code.
+- Preserve app-neutral service behavior; consumer apps own domain workflows.
+- Verify current package README/source before relying on advanced provider features.
+
+## Reference
+
+Read `references/integrations.md` for provider-specific notes.
+
+## Bundled References
+
+### references/integrations.md
+
+# Integration Usage
+
+## Firebase
+
+Use the integration module and service to initialize Firebase Admin clients from validated config. Keep credential files local or environment-provided.
+
+## GPT
+
+Use the integration package for reusable GPT client setup. Keep prompt/business policy in the consumer app, not in the generic package.

package/dist/cursor/.cursor/rules/joktec-mongo-skill.mdc

@@ -0,0 +1,68 @@
+---
+description: Use when working with @joktec/mongo in a consumer app, including MongoModule setup, Typegoose schema decorators, MongoRepo, MongoService, MongoHelper, plugins, ObjectId/query safety, soft delete, strict references, and cursor pagination.
+globs: packages/databases/mongo/**
+alwaysApply: false
+---
+
+# JokTec Mongo Skill
+
+Use this skill for MongoDB-backed resources that rely on JokTec's Mongoose/Typegoose wrapper.
+
+## Rules
+
+- Register app schema classes through `MongoModule.forRoot(...)`.
+- Keep schema classes, app repositories, and app-specific queries in the consumer app.
+- Extend `MongoRepo<T, ID>` for app repositories.
+- Preserve `conId` when the app has multiple Mongo connections.
+- Use schema-first decorators when a schema class should be reused as a DTO source.
+- Treat ObjectId casting and regex behavior as safety-sensitive.
+
+## References
+
+- Read `references/repository.md` for `MongoService`, `MongoRepo`, query parsing, and cursor pagination.
+- Read `references/schema-and-plugins.md` for decorators, paranoid soft delete, strict references, transform behavior, and debug output.
+
+## Bundled References
+
+### references/repository.md
+
+# Mongo Repository Usage
+
+## Module Setup
+
+Register schemas with `MongoModule.forRoot({ conId, models: [...] })`. Use the same `conId` in app repositories when using non-default connections.
+
+## Repository Pattern
+
+Extend `MongoRepo` and pass the schema class to the base constructor. Services can then use `BaseService` from `@joktec/core`.
+
+## Query Safety
+
+- Root `id` can act as an API alias for `_id` in query conditions.
+- ObjectId casting should be schema-aware and limited to `_id`, ObjectId paths, or explicitly configured paths.
+- `$like`, `$begin`, and `$end` escape regex input by default.
+- Do not rely on broad conversion when storing raw snapshots, maps, or nested subdocuments.
+
+## Pagination
+
+`MongoRepo.paginate` supports page, offset, and cursor responses. Cursor mode defaults to `_id`; custom `cursorKey` appends `_id` as a tie-breaker.
+
+### references/schema-and-plugins.md
+
+# Mongo Schema And Plugins
+
+## Schema Decorators
+
+Use `@Schema` and `@Prop` wrappers from `@joktec/mongo` for Typegoose schema metadata plus validation, transform, and Swagger metadata.
+
+Avoid mutating shared option objects across multiple properties.
+
+## Plugins
+
+- Paranoid plugin handles soft delete filtering and must respect aggregate first-stage constraints such as `$geoNear`.
+- Strict reference plugin validates referenced documents and must resolve models through the active connection.
+- Transform plugin centralizes common document transformation and should not break Mongo update operators.
+
+## Debug Output
+
+Use `mongoDebug(collection, method, ...args)` when a Mongoose debug callback should be rendered as a Mongo shell-friendly command.

package/dist/cursor/.cursor/rules/joktec-mysql-skill.mdc

@@ -0,0 +1,69 @@
+---
+description: Use when working with @joktec/mysql in a consumer app, including MysqlModule setup, TypeORM entities, schema-first @Column/@PrimaryColumn decorators, MysqlRepo, MysqlService, transactions, dialect support, uuidv7 ids, query safety, and cursor pagination.
+globs: packages/databases/mysql/**
+alwaysApply: false
+---
+
+# JokTec MySQL Skill
+
+Use this skill for relational resources backed by JokTec's TypeORM wrapper.
+
+## Rules
+
+- Register app entities through `MysqlModule.forRoot(...)`.
+- Keep entities, app repositories, and app-specific SQL in the consumer app.
+- Extend `MysqlRepo<T, ID>` for app repositories.
+- Treat `mysql`, `mariadb`, and `postgres` as the first-class dialects.
+- Keep `sync` explicit and normally enabled only by an owner process or development bootstrap.
+- Do not add new behavior to deprecated `MysqlFinder`; use `MysqlRepo.qb()` and `MysqlHelper` paths.
+
+## References
+
+- Read `references/repository.md` for connection lifecycle, repository usage, query safety, transaction, and cursor behavior.
+- Read `references/entities.md` for `@Tables`, `@Column`, `@PrimaryColumn`, uuidv7, and dialect guidance.
+
+## Bundled References
+
+### references/entities.md
+
+# MySQL Entity Decorators
+
+## Schema-First Entity Pattern
+
+Use `@Tables`, `@Column`, and `@PrimaryColumn` from `@joktec/mysql` when an entity should also act as the source class for mapped DTOs.
+
+## Primary Keys
+
+- Prefer numeric auto-increment keys for write-heavy MySQL tables.
+- Use UUIDs when the app needs globally unique or public identifiers.
+- Prefer `uuidv7` over random UUIDs when the id participates in ordered indexes or cursor-like access.
+
+## Dialects
+
+The stable dialects are MySQL, MariaDB, and Postgres. Dialect capabilities own differences such as `LIKE` vs `ILIKE`, array support, fulltext support, and generated map reliability.
+
+### references/repository.md
+
+# MySQL Repository Usage
+
+## Module Setup
+
+Register entities with `MysqlModule.forRoot({ conId, models: [...] })`. Use `conId` for multiple DataSources.
+
+## Repository Pattern
+
+Extend `MysqlRepo` and pass the entity class to the base constructor. Services can use `BaseService` when CRUD behavior follows the shared contract.
+
+## Query Safety
+
+- Validate field paths against TypeORM metadata before interpolating SQL identifiers.
+- Use parameter binding for values.
+- Keep logical operators such as `$and` and `$or` grouped through QueryBuilder behavior.
+
+## Pagination
+
+`MysqlRepo.paginate` supports page, offset, and cursor responses. Cursor mode defaults to `createdAt` plus primary key columns. Custom cursor keys must be mapped columns.
+
+## Transactions
+
+When using transaction-scoped operations, pass the manager or query runner through repository options so pre-read and write operations use the same context.

package/dist/cursor/.cursor/rules/joktec-tool-skill.mdc

@@ -0,0 +1,44 @@
+---
+description: Use when wiring or using JokTec tool packages @joktec/http, @joktec/file, or @joktec/alert, including Axios-backed HTTP clients, file classification helpers, Slack-compatible alert webhooks, config-driven lifecycle, and app-neutral utility services.
+globs: packages/tools/**
+alwaysApply: false
+---
+
+# JokTec Tool Skill
+
+Use this skill for reusable utility services.
+
+## Packages
+
+- `@joktec/http`: Axios-backed HTTP client wrapper.
+- `@joktec/file`: file classification and local file helpers.
+- `@joktec/alert`: alert delivery through Slack-compatible webhooks.
+
+## Rules
+
+- Keep tools app-neutral and reusable.
+- Use config-driven clients instead of direct ad hoc setup in app code.
+- Preserve retry, metrics, proxy, and upload behavior where the package exposes it.
+- Keep alert tokens and webhook URLs in runtime config only.
+
+## Reference
+
+Read `references/tools.md` for package-specific usage notes.
+
+## Bundled References
+
+### references/tools.md
+
+# Tool Usage
+
+## HTTP
+
+Use `@joktec/http` for Axios-backed requests, uploads, proxy agent support, retry config, and metrics where exposed.
+
+## File
+
+Use `@joktec/file` for shared file helpers and classification behavior instead of duplicating local utility code.
+
+## Alert
+
+Use `@joktec/alert` for Slack-compatible webhook alerts. Keep webhook URLs and credentials out of source control.