@malamute/ai-rules 1.0.0

package/configs/nestjs/.claude/rules/auth.md

@@ -0,0 +1,321 @@
+---
+paths:
+  - "src/**/auth/**/*.ts"
+  - "src/**/*.guard.ts"
+  - "src/**/*.strategy.ts"
+---
+
+# NestJS Authentication
+
+## Passport + JWT Pattern
+
+### Module Structure
+
+```
+src/modules/auth/
+├── auth.module.ts
+├── auth.controller.ts
+├── auth.service.ts
+├── strategies/
+│   ├── jwt.strategy.ts
+│   └── local.strategy.ts
+├── guards/
+│   ├── jwt-auth.guard.ts
+│   └── local-auth.guard.ts
+├── decorators/
+│   ├── current-user.decorator.ts
+│   └── public.decorator.ts
+└── dto/
+    ├── login.dto.ts
+    └── register.dto.ts
+```
+
+### JWT Strategy
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { PassportStrategy } from '@nestjs/passport';
+import { ExtractJwt, Strategy } from 'passport-jwt';
+import { ConfigService } from '@nestjs/config';
+
+export interface JwtPayload {
+  sub: string;
+  email: string;
+  role: string;
+}
+
+@Injectable()
+export class JwtStrategy extends PassportStrategy(Strategy) {
+  constructor(private readonly configService: ConfigService) {
+    super({
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      ignoreExpiration: false,
+      secretOrKey: configService.getOrThrow<string>('JWT_SECRET'),
+    });
+  }
+
+  validate(payload: JwtPayload) {
+    // Returned value is attached to request.user
+    return {
+      id: payload.sub,
+      email: payload.email,
+      role: payload.role,
+    };
+  }
+}
+```
+
+### Local Strategy (Login)
+
+```typescript
+import { Injectable, UnauthorizedException } from '@nestjs/common';
+import { PassportStrategy } from '@nestjs/passport';
+import { Strategy } from 'passport-local';
+import { AuthService } from '../auth.service';
+
+@Injectable()
+export class LocalStrategy extends PassportStrategy(Strategy) {
+  constructor(private readonly authService: AuthService) {
+    super({
+      usernameField: 'email', // Use email instead of username
+    });
+  }
+
+  async validate(email: string, password: string) {
+    const user = await this.authService.validateUser(email, password);
+    if (!user) {
+      throw new UnauthorizedException('Invalid credentials');
+    }
+    return user;
+  }
+}
+```
+
+### Auth Service
+
+```typescript
+import { Injectable, UnauthorizedException } from '@nestjs/common';
+import { JwtService } from '@nestjs/jwt';
+import { UsersService } from '../users/users.service';
+import * as bcrypt from 'bcrypt';
+
+@Injectable()
+export class AuthService {
+  constructor(
+    private readonly usersService: UsersService,
+    private readonly jwtService: JwtService,
+  ) {}
+
+  async validateUser(email: string, password: string) {
+    const user = await this.usersService.findByEmail(email);
+    if (!user) return null;
+
+    const isValid = await bcrypt.compare(password, user.password);
+    if (!isValid) return null;
+
+    const { password: _, ...result } = user;
+    return result;
+  }
+
+  async login(user: { id: string; email: string; role: string }) {
+    const payload: JwtPayload = {
+      sub: user.id,
+      email: user.email,
+      role: user.role,
+    };
+
+    return {
+      accessToken: this.jwtService.sign(payload),
+      user: {
+        id: user.id,
+        email: user.email,
+        role: user.role,
+      },
+    };
+  }
+
+  async register(dto: RegisterDto) {
+    const hashedPassword = await bcrypt.hash(dto.password, 10);
+    const user = await this.usersService.create({
+      ...dto,
+      password: hashedPassword,
+    });
+
+    return this.login(user);
+  }
+}
+```
+
+### Guards
+
+```typescript
+// jwt-auth.guard.ts
+import { Injectable, ExecutionContext } from '@nestjs/common';
+import { AuthGuard } from '@nestjs/passport';
+import { Reflector } from '@nestjs/core';
+import { IS_PUBLIC_KEY } from '../decorators/public.decorator';
+
+@Injectable()
+export class JwtAuthGuard extends AuthGuard('jwt') {
+  constructor(private reflector: Reflector) {
+    super();
+  }
+
+  canActivate(context: ExecutionContext) {
+    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+
+    if (isPublic) {
+      return true;
+    }
+
+    return super.canActivate(context);
+  }
+}
+
+// local-auth.guard.ts
+import { Injectable } from '@nestjs/common';
+import { AuthGuard } from '@nestjs/passport';
+
+@Injectable()
+export class LocalAuthGuard extends AuthGuard('local') {}
+```
+
+### Custom Decorators
+
+```typescript
+// public.decorator.ts
+import { SetMetadata } from '@nestjs/common';
+
+export const IS_PUBLIC_KEY = 'isPublic';
+export const Public = () => SetMetadata(IS_PUBLIC_KEY, true);
+
+// current-user.decorator.ts
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+
+export const CurrentUser = createParamDecorator(
+  (data: string | undefined, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest();
+    const user = request.user;
+    return data ? user?.[data] : user;
+  },
+);
+
+// roles.decorator.ts
+import { SetMetadata } from '@nestjs/common';
+
+export const ROLES_KEY = 'roles';
+export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);
+```
+
+### Roles Guard
+
+```typescript
+import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { ROLES_KEY } from '../decorators/roles.decorator';
+
+@Injectable()
+export class RolesGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const requiredRoles = this.reflector.getAllAndOverride<string[]>(
+      ROLES_KEY,
+      [context.getHandler(), context.getClass()],
+    );
+
+    if (!requiredRoles) {
+      return true;
+    }
+
+    const { user } = context.switchToHttp().getRequest();
+    return requiredRoles.includes(user.role);
+  }
+}
+```
+
+### Controller Usage
+
+```typescript
+@Controller('auth')
+export class AuthController {
+  constructor(private readonly authService: AuthService) {}
+
+  @Public()
+  @UseGuards(LocalAuthGuard)
+  @Post('login')
+  login(@CurrentUser() user) {
+    return this.authService.login(user);
+  }
+
+  @Public()
+  @Post('register')
+  register(@Body() dto: RegisterDto) {
+    return this.authService.register(dto);
+  }
+
+  @Get('profile')
+  getProfile(@CurrentUser() user) {
+    return user;
+  }
+
+  @Roles('admin')
+  @UseGuards(RolesGuard)
+  @Get('admin')
+  adminOnly(@CurrentUser() user) {
+    return { message: 'Admin access granted', user };
+  }
+}
+```
+
+### Module Configuration
+
+```typescript
+@Module({
+  imports: [
+    UsersModule,
+    PassportModule,
+    JwtModule.registerAsync({
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        secret: config.getOrThrow('JWT_SECRET'),
+        signOptions: {
+          expiresIn: config.get('JWT_EXPIRES_IN', '1d'),
+        },
+      }),
+    }),
+  ],
+  controllers: [AuthController],
+  providers: [AuthService, JwtStrategy, LocalStrategy],
+  exports: [AuthService],
+})
+export class AuthModule {}
+```
+
+### Global Guard Setup (app.module.ts)
+
+```typescript
+import { APP_GUARD } from '@nestjs/core';
+
+@Module({
+  providers: [
+    {
+      provide: APP_GUARD,
+      useClass: JwtAuthGuard,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+## Security Best Practices
+
+- Never store plain passwords - always use bcrypt
+- Use environment variables for secrets
+- Set appropriate JWT expiration times
+- Implement refresh token rotation for long sessions
+- Rate limit authentication endpoints
+- Log failed authentication attempts

package/configs/nestjs/.claude/rules/database/prisma.md

@@ -0,0 +1,305 @@
+---
+paths:
+  - "prisma/**/*.prisma"
+  - "src/**/*.repository.ts"
+  - "src/**/prisma*.ts"
+---
+
+# NestJS with Prisma
+
+## Setup
+
+### Prisma Module
+
+```typescript
+// prisma/prisma.module.ts
+import { Global, Module } from '@nestjs/common';
+import { PrismaService } from './prisma.service';
+
+@Global()
+@Module({
+  providers: [PrismaService],
+  exports: [PrismaService],
+})
+export class PrismaModule {}
+
+// prisma/prisma.service.ts
+import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
+import { PrismaClient } from '@prisma/client';
+
+@Injectable()
+export class PrismaService
+  extends PrismaClient
+  implements OnModuleInit, OnModuleDestroy
+{
+  async onModuleInit() {
+    await this.$connect();
+  }
+
+  async onModuleDestroy() {
+    await this.$disconnect();
+  }
+}
+```
+
+## Schema Design
+
+### Model Conventions
+
+```prisma
+// prisma/schema.prisma
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        String   @id @default(uuid())
+  email     String   @unique
+  password  String
+  name      String?
+  role      Role     @default(USER)
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  posts     Post[]
+  profile   Profile?
+
+  @@map("users")
+}
+
+model Post {
+  id          String   @id @default(uuid())
+  title       String
+  content     String?
+  published   Boolean  @default(false)
+  createdAt   DateTime @default(now()) @map("created_at")
+  updatedAt   DateTime @updatedAt @map("updated_at")
+
+  author      User     @relation(fields: [authorId], references: [id], onDelete: Cascade)
+  authorId    String   @map("author_id")
+
+  categories  Category[]
+
+  @@index([authorId])
+  @@map("posts")
+}
+
+enum Role {
+  USER
+  ADMIN
+}
+```
+
+### Naming Conventions
+
+- Models: PascalCase (`User`, `BlogPost`)
+- Fields: camelCase (`createdAt`, `authorId`)
+- Database tables: snake_case via `@@map("users")`
+- Database columns: snake_case via `@map("created_at")`
+
+## Repository Pattern
+
+```typescript
+// users/users.repository.ts
+import { Injectable } from '@nestjs/common';
+import { PrismaService } from '../prisma/prisma.service';
+import { Prisma, User } from '@prisma/client';
+
+@Injectable()
+export class UsersRepository {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async findById(id: string): Promise<User | null> {
+    return this.prisma.user.findUnique({
+      where: { id },
+    });
+  }
+
+  async findByEmail(email: string): Promise<User | null> {
+    return this.prisma.user.findUnique({
+      where: { email },
+    });
+  }
+
+  async findMany(params: {
+    skip?: number;
+    take?: number;
+    where?: Prisma.UserWhereInput;
+    orderBy?: Prisma.UserOrderByWithRelationInput;
+  }): Promise<User[]> {
+    const { skip, take, where, orderBy } = params;
+    return this.prisma.user.findMany({
+      skip,
+      take,
+      where,
+      orderBy,
+    });
+  }
+
+  async create(data: Prisma.UserCreateInput): Promise<User> {
+    return this.prisma.user.create({ data });
+  }
+
+  async update(id: string, data: Prisma.UserUpdateInput): Promise<User> {
+    return this.prisma.user.update({
+      where: { id },
+      data,
+    });
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.prisma.user.delete({ where: { id } });
+  }
+}
+```
+
+## Query Patterns
+
+### Select Specific Fields
+
+```typescript
+// Return only needed fields
+const user = await this.prisma.user.findUnique({
+  where: { id },
+  select: {
+    id: true,
+    email: true,
+    name: true,
+    // password excluded
+  },
+});
+```
+
+### Include Relations
+
+```typescript
+const userWithPosts = await this.prisma.user.findUnique({
+  where: { id },
+  include: {
+    posts: {
+      where: { published: true },
+      orderBy: { createdAt: 'desc' },
+      take: 10,
+    },
+  },
+});
+```
+
+### Pagination
+
+```typescript
+async findPaginated(page: number, limit: number) {
+  const [data, total] = await Promise.all([
+    this.prisma.user.findMany({
+      skip: (page - 1) * limit,
+      take: limit,
+      orderBy: { createdAt: 'desc' },
+    }),
+    this.prisma.user.count(),
+  ]);
+
+  return {
+    data,
+    meta: {
+      total,
+      page,
+      limit,
+      totalPages: Math.ceil(total / limit),
+    },
+  };
+}
+```
+
+### Transactions
+
+```typescript
+async transferCredits(fromId: string, toId: string, amount: number) {
+  return this.prisma.$transaction(async (tx) => {
+    const sender = await tx.user.update({
+      where: { id: fromId },
+      data: { credits: { decrement: amount } },
+    });
+
+    if (sender.credits < 0) {
+      throw new Error('Insufficient credits');
+    }
+
+    await tx.user.update({
+      where: { id: toId },
+      data: { credits: { increment: amount } },
+    });
+
+    return { success: true };
+  });
+}
+```
+
+### Soft Delete Pattern
+
+```prisma
+model User {
+  id        String    @id @default(uuid())
+  deletedAt DateTime? @map("deleted_at")
+  // ...
+}
+```
+
+```typescript
+// Middleware approach
+this.prisma.$use(async (params, next) => {
+  if (params.model === 'User') {
+    if (params.action === 'delete') {
+      params.action = 'update';
+      params.args['data'] = { deletedAt: new Date() };
+    }
+    if (params.action === 'findMany' || params.action === 'findFirst') {
+      params.args['where'] = {
+        ...params.args['where'],
+        deletedAt: null,
+      };
+    }
+  }
+  return next(params);
+});
+```
+
+## Migrations
+
+```bash
+# Create migration
+npx prisma migrate dev --name add_users_table
+
+# Apply migrations (production)
+npx prisma migrate deploy
+
+# Reset database (dev only)
+npx prisma migrate reset
+
+# Generate client after schema change
+npx prisma generate
+```
+
+## Testing with Prisma
+
+```typescript
+// Mock PrismaService
+const mockPrismaService = {
+  user: {
+    findUnique: jest.fn(),
+    findMany: jest.fn(),
+    create: jest.fn(),
+    update: jest.fn(),
+    delete: jest.fn(),
+  },
+};
+
+// E2E: Use test database
+// .env.test
+DATABASE_URL="postgresql://localhost:5432/myapp_test"
+```