@malamute/ai-rules 1.4.0 → 1.5.1

package/configs/adonisjs/rules/core.md

@@ -0,0 +1,95 @@
+---
+description: "AdonisJS 6+ project conventions and architecture"
+alwaysApply: true
+---
+
+# AdonisJS Project Guidelines
+
+## Stack
+
+- AdonisJS 6+
+- TypeScript strict mode
+- Node.js 20+
+- Japa (test framework)
+- Lucid ORM
+
+## Architecture
+
+```
+├── app/
+│   ├── controllers/
+│   ├── models/
+│   ├── services/
+│   ├── validators/
+│   ├── middleware/
+│   ├── exceptions/
+│   └── mails/
+├── config/
+├── database/
+│   ├── migrations/
+│   ├── seeders/
+│   └── factories/
+├── resources/
+│   └── views/
+├── start/
+│   ├── routes.ts
+│   ├── kernel.ts
+│   └── events.ts
+├── tests/
+└── adonisrc.ts
+```
+
+## Request Lifecycle
+
+```
+Request → Global Middleware → Route Middleware → Controller → Response
+```
+
+## Core Principles
+
+### Layer Responsibilities
+
+| Layer | Responsibility |
+|-------|---------------|
+| Controller | HTTP handling, delegates to services |
+| Service | Business logic |
+| Model | Data structure, relationships, hooks |
+| Validator | Input validation with VineJS |
+
+### Naming Conventions
+
+- Controllers: `UsersController` (plural)
+- Models: `User` (singular)
+- Validators: `CreateUserValidator`
+- Migrations: `TIMESTAMP_create_users_table`
+
+### Dependency Injection
+
+Use the IoC container:
+```typescript
+@inject()
+export default class UsersController {
+  constructor(private userService: UserService) {}
+}
+```
+
+## Commands
+
+```bash
+node ace serve --watch     # Dev server
+node ace build             # Production build
+node ace test              # Run tests
+node ace make:controller   # Generate controller
+node ace make:model        # Generate model
+node ace make:validator    # Generate validator
+node ace make:service      # Generate service
+node ace migration:run     # Run migrations
+node ace migration:rollback
+```
+
+## Code Style
+
+- Use `@inject()` decorator for DI
+- Async methods return `Promise<T>`
+- Use `HttpContext` for request/response
+- Validators use VineJS schema

package/configs/adonisjs/rules/database/lucid.md

@@ -0,0 +1,167 @@
+---
+paths:
+  - "app/models/**/*.ts"
+  - "database/migrations/**/*.ts"
+  - "database/seeders/**/*.ts"
+  - "database/factories/**/*.ts"
+---
+
+# Lucid ORM
+
+## Models
+
+```typescript
+import { DateTime } from 'luxon'
+import { BaseModel, column, hasMany, belongsTo } from '@adonisjs/lucid/orm'
+import type { HasMany, BelongsTo } from '@adonisjs/lucid/types/relations'
+import Post from '#models/post'
+import Role from '#models/role'
+
+export default class User extends BaseModel {
+  @column({ isPrimary: true })
+  declare id: number
+
+  @column()
+  declare email: string
+
+  @column({ serializeAs: null })
+  declare password: string
+
+  @column()
+  declare roleId: number
+
+  @column.dateTime({ autoCreate: true })
+  declare createdAt: DateTime
+
+  @column.dateTime({ autoCreate: true, autoUpdate: true })
+  declare updatedAt: DateTime
+
+  // Relationships
+  @hasMany(() => Post)
+  declare posts: HasMany<typeof Post>
+
+  @belongsTo(() => Role)
+  declare role: BelongsTo<typeof Role>
+}
+```
+
+## Relationships
+
+```typescript
+// One to Many
+@hasMany(() => Post)
+declare posts: HasMany<typeof Post>
+
+// Belongs To
+@belongsTo(() => User)
+declare user: BelongsTo<typeof User>
+
+// Many to Many
+@manyToMany(() => Tag, {
+  pivotTable: 'post_tags',
+  pivotTimestamps: true,
+})
+declare tags: ManyToMany<typeof Tag>
+
+// Has One
+@hasOne(() => Profile)
+declare profile: HasOne<typeof Profile>
+```
+
+## Queries
+
+```typescript
+// Find
+const user = await User.find(1)
+const user = await User.findOrFail(1)
+const user = await User.findBy('email', 'user@example.com')
+
+// Query builder
+const users = await User.query()
+  .where('isActive', true)
+  .whereNotNull('verifiedAt')
+  .orderBy('createdAt', 'desc')
+  .limit(10)
+
+// With relationships
+const user = await User.query()
+  .where('id', 1)
+  .preload('posts', (query) => {
+    query.where('isPublished', true)
+  })
+  .firstOrFail()
+
+// Aggregates
+const count = await User.query().count('* as total')
+```
+
+## Migrations
+
+```typescript
+import { BaseSchema } from '@adonisjs/lucid/schema'
+
+export default class extends BaseSchema {
+  protected tableName = 'users'
+
+  async up() {
+    this.schema.createTable(this.tableName, (table) => {
+      table.increments('id')
+      table.string('email').notNullable().unique()
+      table.string('password').notNullable()
+      table.integer('role_id').unsigned().references('roles.id').onDelete('CASCADE')
+      table.timestamp('created_at')
+      table.timestamp('updated_at')
+    })
+  }
+
+  async down() {
+    this.schema.dropTable(this.tableName)
+  }
+}
+```
+
+## Factories
+
+```typescript
+import Factory from '@adonisjs/lucid/factories'
+import User from '#models/user'
+
+export const UserFactory = Factory.define(User, ({ faker }) => ({
+  email: faker.internet.email(),
+  password: faker.internet.password(),
+}))
+  .relation('posts', () => PostFactory)
+  .build()
+
+// Usage
+const user = await UserFactory.create()
+const users = await UserFactory.createMany(5)
+const userWithPosts = await UserFactory.with('posts', 3).create()
+```
+
+## Hooks
+
+```typescript
+import { beforeSave } from '@adonisjs/lucid/orm'
+import hash from '@adonisjs/core/services/hash'
+
+export default class User extends BaseModel {
+  @beforeSave()
+  static async hashPassword(user: User) {
+    if (user.$dirty.password) {
+      user.password = await hash.make(user.password)
+    }
+  }
+}
+```
+
+## Transactions
+
+```typescript
+import db from '@adonisjs/lucid/services/db'
+
+await db.transaction(async (trx) => {
+  const user = await User.create({ email, password }, { client: trx })
+  await Profile.create({ userId: user.id }, { client: trx })
+})
+```

package/configs/adonisjs/rules/middleware.md

@@ -0,0 +1,140 @@
+---
+paths:
+  - "app/middleware/**/*.ts"
+  - "start/kernel.ts"
+---
+
+# AdonisJS Middleware
+
+## Creating Middleware
+
+```typescript
+// app/middleware/admin_middleware.ts
+import type { HttpContext } from '@adonisjs/core/http'
+import type { NextFn } from '@adonisjs/core/types/http'
+
+export default class AdminMiddleware {
+  async handle({ auth, response }: HttpContext, next: NextFn) {
+    if (auth.user?.role !== 'admin') {
+      return response.forbidden({ message: 'Admin access required' })
+    }
+
+    await next()
+  }
+}
+```
+
+## Register Middleware
+
+```typescript
+// start/kernel.ts
+import router from '@adonisjs/core/services/router'
+
+// Named middleware (use on specific routes)
+router.named({
+  auth: () => import('#middleware/auth_middleware'),
+  admin: () => import('#middleware/admin_middleware'),
+  verified: () => import('#middleware/verified_middleware'),
+})
+```
+
+## Using Middleware
+
+```typescript
+// start/routes.ts
+import router from '@adonisjs/core/services/router'
+import { middleware } from '#start/kernel'
+
+// Single middleware
+router.get('dashboard', [DashboardController, 'index'])
+  .use(middleware.auth())
+
+// Multiple middleware
+router.get('admin', [AdminController, 'index'])
+  .use([middleware.auth(), middleware.admin()])
+
+// Group middleware
+router.group(() => {
+  router.get('profile', [ProfileController, 'show'])
+  router.put('profile', [ProfileController, 'update'])
+}).use(middleware.auth())
+```
+
+## Middleware with Parameters
+
+```typescript
+// app/middleware/role_middleware.ts
+import type { HttpContext } from '@adonisjs/core/http'
+import type { NextFn } from '@adonisjs/core/types/http'
+
+export default class RoleMiddleware {
+  async handle({ auth, response }: HttpContext, next: NextFn, options: { roles: string[] }) {
+    if (!options.roles.includes(auth.user!.role)) {
+      return response.forbidden({ message: 'Insufficient permissions' })
+    }
+
+    await next()
+  }
+}
+
+// Usage
+router.get('reports', [ReportsController, 'index'])
+  .use(middleware.role({ roles: ['admin', 'manager'] }))
+```
+
+## Request Logging Middleware
+
+```typescript
+import type { HttpContext } from '@adonisjs/core/http'
+import type { NextFn } from '@adonisjs/core/types/http'
+import logger from '@adonisjs/core/services/logger'
+
+export default class RequestLoggerMiddleware {
+  async handle({ request }: HttpContext, next: NextFn) {
+    const start = Date.now()
+
+    await next()
+
+    const duration = Date.now() - start
+    logger.info(`${request.method()} ${request.url()} - ${duration}ms`)
+  }
+}
+```
+
+## Global Middleware
+
+```typescript
+// start/kernel.ts
+import server from '@adonisjs/core/services/server'
+
+// Server middleware (runs for every request)
+server.use([
+  () => import('#middleware/container_bindings_middleware'),
+  () => import('#middleware/force_json_response_middleware'),
+])
+
+// Router middleware (runs for routes only)
+router.use([
+  () => import('@adonisjs/core/bodyparser_middleware'),
+  () => import('#middleware/request_logger_middleware'),
+])
+```
+
+## Terminate Hook
+
+```typescript
+export default class AnalyticsMiddleware {
+  async handle(ctx: HttpContext, next: NextFn) {
+    await next()
+  }
+
+  // Runs after response is sent
+  async terminate(ctx: HttpContext) {
+    await Analytics.track({
+      path: ctx.request.url(),
+      userId: ctx.auth.user?.id,
+      duration: ctx.response.getResponseTime(),
+    })
+  }
+}
+```

package/configs/adonisjs/rules/services.md

@@ -0,0 +1,154 @@
+---
+paths:
+  - "app/services/**/*.ts"
+---
+
+# AdonisJS Services
+
+## Structure
+
+Services contain business logic. Controllers delegate to services.
+
+```typescript
+// app/services/user_service.ts
+import { inject } from '@adonisjs/core'
+import User from '#models/user'
+import hash from '@adonisjs/core/services/hash'
+
+@inject()
+export default class UserService {
+  async getAll() {
+    return User.query().orderBy('createdAt', 'desc')
+  }
+
+  async findOrFail(id: number) {
+    return User.findOrFail(id)
+  }
+
+  async create(data: { email: string; password: string; name: string }) {
+    return User.create({
+      ...data,
+      password: await hash.make(data.password),
+    })
+  }
+
+  async update(id: number, data: Partial<{ email: string; name: string }>) {
+    const user = await User.findOrFail(id)
+    user.merge(data)
+    await user.save()
+    return user
+  }
+
+  async delete(id: number) {
+    const user = await User.findOrFail(id)
+    await user.delete()
+  }
+}
+```
+
+## Service with Dependencies
+
+```typescript
+import { inject } from '@adonisjs/core'
+import mail from '@adonisjs/mail/services/main'
+import User from '#models/user'
+import NotificationService from '#services/notification_service'
+
+@inject()
+export default class OrderService {
+  constructor(private notificationService: NotificationService) {}
+
+  async create(userId: number, items: OrderItem[]) {
+    const user = await User.findOrFail(userId)
+
+    const order = await Order.create({
+      userId,
+      total: this.calculateTotal(items),
+    })
+
+    await order.related('items').createMany(items)
+
+    // Use injected service
+    await this.notificationService.sendOrderConfirmation(user, order)
+
+    return order
+  }
+
+  private calculateTotal(items: OrderItem[]): number {
+    return items.reduce((sum, item) => sum + item.price * item.quantity, 0)
+  }
+}
+```
+
+## Register in Container (optional)
+
+For complex setup or interfaces:
+
+```typescript
+// providers/app_provider.ts
+import type { ApplicationService } from '@adonisjs/core/types'
+
+export default class AppProvider {
+  constructor(protected app: ApplicationService) {}
+
+  async boot() {
+    const { default: PaymentService } = await import('#services/payment_service')
+
+    this.app.container.singleton('payment', () => {
+      return new PaymentService(env.get('STRIPE_KEY'))
+    })
+  }
+}
+```
+
+## Error Handling
+
+```typescript
+import { Exception } from '@adonisjs/core/exceptions'
+
+export class InsufficientFundsException extends Exception {
+  static status = 422
+  static code = 'E_INSUFFICIENT_FUNDS'
+}
+
+export default class WalletService {
+  async withdraw(userId: number, amount: number) {
+    const wallet = await Wallet.findByOrFail('userId', userId)
+
+    if (wallet.balance < amount) {
+      throw new InsufficientFundsException('Insufficient funds')
+    }
+
+    wallet.balance -= amount
+    await wallet.save()
+    return wallet
+  }
+}
+```
+
+## Testing Services
+
+```typescript
+import { test } from '@japa/runner'
+import UserService from '#services/user_service'
+import { UserFactory } from '#database/factories/user_factory'
+
+test.group('UserService', (group) => {
+  group.each.setup(async () => {
+    await Database.beginGlobalTransaction()
+    return () => Database.rollbackGlobalTransaction()
+  })
+
+  test('creates user with hashed password', async ({ assert }) => {
+    const service = new UserService()
+
+    const user = await service.create({
+      email: 'test@example.com',
+      password: 'plaintext',
+      name: 'Test',
+    })
+
+    assert.notEqual(user.password, 'plaintext')
+  })
+})
+```