@joktec/skills 0.1.4 → 0.1.8

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

@@ -16,8 +16,12 @@ Use this skill for relational resources backed by JokTec's TypeORM wrapper.
 - 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.
-- When migrating an entity to the new schema-first decorators, migrate the whole property decorator stack, not only the TypeORM primary key decorator.
-- If guidance is insufficient, read this skill's references and inspect `../joktec-framework` package source or GitHub fallback before assuming APIs.
+- Use schema-first `@Column`, `@PrimaryColumn`, and `@TimestampColumn` wrappers when an entity also acts as DTO metadata.
+- Use `@Column({ kind: 'virtual' })` for computed getters that need expose/Swagger metadata without persistence.
+- Use `immutable` for API read-only metadata; TypeORM `update: false` remains storage write behavior and is also inferred as Swagger read-only when `immutable` is not set.
+- Do not add `swagger.type` just because a column has a primitive, date, array, nested JSON class, or relation type. The wrapper infers Swagger metadata from TypeScript design type and JokTec options. Use `swagger` only to override an inferred shape.
+- Do not use `@joktec/mysql` for Mongo/ObjectId columns, even though TypeORM has Mongo-related APIs.
+- For real migrations, inspect the installed `@joktec/mysql` source in the consumer project's `node_modules` first. If that is insufficient, read GitHub package docs, then GitHub source. Use the local `../joktec-framework` checkout only when you are working inside the JokTec development workspace.
 
 ## References
 
@@ -32,13 +36,29 @@ Use this skill for relational resources backed by JokTec's TypeORM wrapper.
 
 ## Source Lookup
 
-When blocked, inspect:
+When blocked in a consumer project, inspect the installed package first:
+
+- `node_modules/@joktec/mysql/README.md`
+- `node_modules/@joktec/mysql/AGENTS.md` when published with the package
+- `node_modules/@joktec/mysql/dist/index.d.ts`
+- `node_modules/@joktec/mysql/dist/decorators/column.decorator.d.ts`
+- `node_modules/@joktec/mysql/dist/decorators/columns/column.type.d.ts`
+- `node_modules/@joktec/mysql/dist/decorators/timestamp.decorator.d.ts`
+
+If the installed package is missing enough detail, use the GitHub package docs next:
+
+- `https://github.com/joktec/joktec-framework/tree/main/packages/databases/mysql`
+
+Use GitHub source only after package docs and installed types are not enough:
 
 - `packages/databases/mysql/src/decorators/table.decorator.ts`
 - `packages/databases/mysql/src/decorators/column.decorator.ts`
 - `packages/databases/mysql/src/decorators/columns/column.type.ts`
 - `packages/databases/mysql/src/decorators/columns/column.factory.ts`
 - `packages/databases/mysql/src/decorators/columns/primary.column.ts`
+- `packages/databases/mysql/src/decorators/columns/timestamp.column.ts`
+- `packages/databases/mysql/src/decorators/columns/virtual.column.ts`
+- `packages/databases/mysql/src/decorators/columns/object.column.ts`
 - `packages/databases/mysql/src/decorators/columns/string.column.ts`
 - `packages/databases/mysql/src/decorators/columns/number.column.ts`
 - `packages/databases/mysql/src/decorators/columns/transform.column.ts`
@@ -46,7 +66,7 @@ When blocked, inspect:
 
 ## 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.
+Use `@Tables`, `@Column`, `@PrimaryColumn`, and `@TimestampColumn` from `@joktec/mysql` when an entity should also act as the source class for mapped DTOs.
 
 The new decorators are not thin TypeORM aliases. They are schema-first wrappers that compose:
 
@@ -55,11 +75,19 @@ The new decorators are not thin TypeORM aliases. They are schema-first wrappers
 - `class-transformer` expose/exclude behavior.
 - Swagger property metadata.
 
-When migrating old entities, remove duplicate property decorators from `typeorm`, `class-validator`, `class-transformer`, and Swagger when the wrapper option can represent the same behavior.
+The wrapper can also represent virtual computed getters and nested JSON/jsonb class payloads. Do not use this package for Mongo/ObjectId columns.
+
+Wrapper philosophy:
+
+- prefer one schema declaration that carries persistence, validation, transform, and Swagger metadata
+- use wrapper options before duplicating `@ApiProperty`, `@Expose`, `@Type`, or common validators
+- do not add `swagger.type` for normal scalar/date fields, arrays, nested JSON classes, or relations when the wrapper can infer the shape
+- use raw TypeORM only for advanced cases that the wrapper does not model cleanly
+- keep storage write behavior and API documentation behavior distinct when needed
 
-## Legacy Decorator Migration
+## Current Decorator Capabilities
 
-Migrate a whole property at a time. Do not only replace `PrimaryGeneratedColumn`.
+Use the package README and actual installed source for full migration details. This skill only keeps the common mappings that help an agent recognize old patterns.
 
 Common mappings:
 
@@ -68,11 +96,21 @@ Common mappings:
 | `@PrimaryGeneratedColumn()` | `@PrimaryColumn('increment')` |
 | `@PrimaryGeneratedColumn('uuid')` | `@PrimaryColumn('uuid')` |
 | app-generated ordered UUID id | `@PrimaryColumn('uuidv7')` |
+| `@CreateDateColumn(...)` | `@TimestampColumn('create', ...)` |
+| `@UpdateDateColumn(...)` | `@TimestampColumn('update', ...)` |
+| `@DeleteDateColumn(...)` | `@TimestampColumn('delete', ...)` |
+| TypeORM `@VersionColumn(...)` | `@Column({ kind: 'version', ... })` |
+| TypeORM `@VirtualColumn(...)` | `@Column({ kind: 'virtual', mode: 'sql', query, ... })` |
+| TypeORM `@ViewColumn(...)` | `@Column({ kind: 'view', ... })` |
 | `@Column(...)` | `@Column(...)` from `@joktec/mysql` |
+| `@RelationId(...)` | `@Column({ kind: 'relation-id', relationId })` |
 | `@IsNotEmpty()` | `@Column({ required: true })` |
 | `@IsOptional()` | `@Column({ required: false })` or nullable TypeORM option when storage allows null |
 | `@IsEmail()` | `@Column({ isEmail: true })` |
 | `@IsMobilePhone()` | `@Column({ isPhone: true })` |
+| `@IsInt()` | `@Column({ isInt: true })` or an integer column type |
+| `@IsUUID()` | `@Column({ isUUID: true })` |
+| `@IsObject()` | `@Column({ isObject: true })` or a JSON column |
 | `@IsHexColor()` | `@Column({ isHexColor: true })` |
 | `@IsUrl()` | `@Column({ isUrl: true })` |
 | `@MinLength(n)` | `@Column({ minLength: n })` |
@@ -82,54 +120,49 @@ Common mappings:
 | `@Expose()` | default behavior of `@Column(...)` |
 | `@Expose({ groups })` | `@Column({ groups })` |
 | `@Exclude({ toPlainOnly: true })` plus hidden Swagger | `@Column({ hidden: true })` |
-| `@ApiProperty(...)` | `@Column({ swagger: ... })`, or native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength` |
-
-Preserve decorators only when the wrapper cannot express them, by passing them through `decorators: [...]`.
-
-Migration checklist:
-
-- Replace TypeORM column decorators with wrappers from `@joktec/mysql`.
-- Remove duplicate `class-validator` decorators when equivalent wrapper options exist.
-- Remove duplicate `class-transformer` decorators when `hidden` or `groups` expresses the same behavior.
-- Move Swagger examples/descriptions/limits into wrapper options where possible.
-- Preserve custom validators/transforms only through `decorators: [...]`.
-- Keep database-specific options such as `type`, `length`, `nullable`, `unique`, `default`, `enum`, and `comment`.
-- Rebuild and run entity-related tests after migration because DTO metadata and TypeORM metadata both change.
-
-Example migration:
-
-```ts
-// Before
-@Column({ type: 'varchar', length: 255 })
-@IsEmail()
-@IsNotEmpty()
-@Expose()
-@ApiProperty({ example: 'user@example.com' })
-email!: string;
-
-// After
-@Column('varchar', {
-  length: 255,
-  required: true,
-  isEmail: true,
-  example: 'user@example.com',
-})
-email!: string;
-```
-
-For hidden fields:
-
-```ts
-// Before
-@Column({ type: 'varchar', length: 255 })
-@Exclude({ toPlainOnly: true })
-@ApiHideProperty()
-password!: string;
-
-// After
-@Column('varchar', { length: 255, hidden: true })
-password!: string;
-```
+| `@ApiProperty(...)` | Prefer native options such as `example`, `comment`, `deprecated`, `min`, `max`, `minLength`, `maxLength`; use `swagger` only as an override |
+| `@ValidateNested()` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference })` |
+| `@ValidateNested({ each: true })` + `@Type(() => Preference)` | `@Column('jsonb', { nested: Preference, each: true })` |
+| `@Expose()` + `@ApiProperty(...)` on a getter | `@Column({ kind: 'virtual', ... })` |
+| Swagger `readOnly: true` | `@Column({ immutable: true })` or TypeORM `update: false` when ORM updates must also be blocked |
+
+## Swagger Metadata Rules
+
+The `@Column` wrapper already composes Swagger metadata. During migrations, keep entity code small and avoid redundant `swagger` declarations:
+
+- Do not add `swagger: { type: String }` for string columns.
+- Do not add `swagger: { type: Number }` for numeric columns.
+- Do not add `swagger: { type: Boolean }` for boolean columns.
+- Do not add `swagger: { type: Date }` for date, datetime, or timestamp columns.
+- Do not add `swagger: { type: String, isArray: true }` for `simple-array` or reflected array fields unless the OpenAPI shape must differ from the entity field.
+- Do not add `swagger: { type: NestedClass }` when `nested: NestedClass` is already present.
+- Do not add `swagger: { type: () => Entity }` on `Column({ kind: 'relation', type: () => Entity })`; the relation wrapper keeps the Swagger type lazy to avoid circular schema evaluation.
+
+Use `swagger` only for actual overrides, for example:
+
+- an OpenAPI primitive differs from the TypeScript property type, such as a SQL decimal represented as `string`
+- a property needs `oneOf`, `anyOf`, `allOf`, custom `items`, or a deliberately shortened example
+- a generated schema needs an explicit read/write/deprecated override that cannot be represented by wrapper options
+
+If a relation wrapper still triggers a circular Swagger error in a consumer project, inspect `node_modules/@joktec/mysql/dist/decorators/column.decorator.d.ts` and the installed implementation first. Do not paper over the issue by adding `swagger.type` to every relation; identify whether the installed package version has lazy relation Swagger support.
+
+## Read-Only Metadata
+
+`immutable` is the API read-only hint used by the JokTec MySQL wrapper. TypeORM `update: false` is the ORM write behavior. The wrapper maps both to Swagger `readOnly` when appropriate:
+
+- `immutable` has priority over `update: false`
+- `update: false` implies Swagger `readOnly` only when `immutable` is not set
+- `swagger.readOnly` remains the final explicit override
+
+Some field kinds default to API read-only because they are system-managed or computed:
+
+- primary keys
+- timestamp columns
+- version columns
+- view columns
+- virtual getter and SQL virtual columns
+- relation-id columns
+- tree level columns
 
 ## Primary Keys
 
@@ -150,7 +183,21 @@ The stable dialects are MySQL, MariaDB, and Postgres. Dialect capabilities own d
 
 ## Source Lookup
 
-When blocked, inspect:
+When blocked in a consumer project, inspect installed package docs and types first:
+
+- `node_modules/@joktec/mysql/README.md`
+- `node_modules/@joktec/mysql/AGENTS.md` when published with the package
+- `node_modules/@joktec/mysql/dist/index.d.ts`
+- `node_modules/@joktec/mysql/dist/mysql.module.d.ts`
+- `node_modules/@joktec/mysql/dist/mysql.service.d.ts`
+- `node_modules/@joktec/mysql/dist/mysql.repo.d.ts`
+- `node_modules/@joktec/mysql/dist/models/mysql.request.d.ts`
+
+If the installed package is insufficient, read GitHub package docs next:
+
+- `https://github.com/joktec/joktec-framework/tree/main/packages/databases/mysql`
+
+Use GitHub source only after installed types and package docs are not enough:
 
 - `packages/databases/mysql/README.md`
 - `packages/databases/mysql/AGENTS.md`

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

@@ -51,6 +51,7 @@ Best practice:
 - Use the package service for outbound HTTP so retry/proxy/metrics behavior stays centralized.
 - Keep external endpoint URLs and credentials in runtime config.
 - Be careful with ESM/CommonJS import changes in HTTP/Axios ecosystem packages.
+- `HttpService.buildAgent(proxy, opts)` expects proxy identity in `HttpProxyConfig` and agent tuning in Node `AgentOptions`; inspect the installed source before adapting to proxy-agent major-version changes.
 - Test request behavior with mocks unless the test is an explicit consumer integration scenario.
 
 ## File