@malamute/ai-rules 1.0.0 → 1.2.0

package/configs/nestjs/CLAUDE.md

@@ -4,260 +4,102 @@
 
 ## Stack
 
-- NestJS 10+ (latest stable)
+- NestJS 11+
 - TypeScript strict mode
 - Node.js 20+
-- Jest for testing
-- Supertest for E2E
+- Vitest + Supertest
+- Prisma or TypeORM
 
-## Architecture
-
-### Modular Monolith (Recommended)
+## Architecture - Modular Monolith
 
 ```
 src/
 ├── modules/
-│   ├── users/
-│   │   ├── users.module.ts
-│   │   ├── users.controller.ts
-│   │   ├── users.service.ts
+│   ├── [feature]/
+│   │   ├── [feature].module.ts
+│   │   ├── [feature].controller.ts
+│   │   ├── [feature].service.ts
+│   │   ├── [feature].repository.ts
 │   │   ├── dto/
-│   │   │   ├── create-user.dto.ts
-│   │   │   └── update-user.dto.ts
-│   │   ├── entities/
-│   │   │   └── user.entity.ts
-│   │   └── users.repository.ts
-│   │
-│   ├── auth/
-│   │   ├── auth.module.ts
-│   │   ├── auth.controller.ts
-│   │   ├── auth.service.ts
-│   │   ├── strategies/
-│   │   │   ├── jwt.strategy.ts
-│   │   │   └── local.strategy.ts
-│   │   └── guards/
-│   │       └── jwt-auth.guard.ts
-│   │
-│   └── [feature]/
-│       └── ...
-│
+│   │   └── entities/
+│   └── auth/
+│       ├── strategies/
+│       └── guards/
 ├── common/
 │   ├── decorators/
 │   ├── filters/
 │   ├── guards/
 │   ├── interceptors/
 │   └── pipes/
-│
 ├── config/
-│   ├── config.module.ts
-│   └── database.config.ts
-│
 ├── app.module.ts
 └── main.ts
 ```
 
-### Module Principles
-
-- **Single Responsibility**: Each module owns one domain
-- **Clear Boundaries**: Modules communicate via exported services
-- **In-Memory Communication**: Direct method calls, not HTTP between modules
-- **Barrel Exports**: Use `index.ts` for clean imports
+## Request Lifecycle
 
-## Code Style
+```
+Request → Middleware → Guard → Interceptor (pre) → Pipe → Controller → Interceptor (post) → Response
+```
 
-### Controllers
+## Core Principles
 
-- Handle HTTP concerns only (request/response)
-- Delegate business logic to services
-- Use DTOs for all inputs
-- Return consistent response shapes
+### Module Design
 
-```typescript
-@Controller('users')
-export class UsersController {
-  constructor(private readonly usersService: UsersService) {}
+- **Single Responsibility**: One module = one domain
+- **Clear Boundaries**: Communicate via exported services only
+- **Barrel Exports**: Use `index.ts` for clean imports
 
-  @Post()
-  @HttpCode(HttpStatus.CREATED)
-  create(@Body() createUserDto: CreateUserDto): Promise<User> {
-    return this.usersService.create(createUserDto);
-  }
+### Layer Responsibilities
 
-  @Get(':id')
-  findOne(@Param('id', ParseUUIDPipe) id: string): Promise<User> {
-    return this.usersService.findOne(id);
-  }
-}
-```
+| Layer | Responsibility |
+|-------|---------------|
+| Controller | HTTP only, delegates to service |
+| Service | All business logic |
+| Repository | Data access only |
+| DTO | Validation with class-validator |
 
-### Services
+### Exception Handling
 
-- Contain all business logic
-- Inject repositories/other services
-- Throw appropriate NestJS exceptions
+Use built-in NestJS exceptions:
+- `NotFoundException` - 404
+- `BadRequestException` - 400
+- `UnauthorizedException` - 401
+- `ForbiddenException` - 403
+- `ConflictException` - 409
 
-```typescript
-@Injectable()
-export class UsersService {
-  constructor(private readonly usersRepository: UsersRepository) {}
+### Validation (Global)
 
-  async findOne(id: string): Promise<User> {
-    const user = await this.usersRepository.findById(id);
-    if (!user) {
-      throw new NotFoundException(`User with ID ${id} not found`);
-    }
-    return user;
-  }
-}
-```
+Enable global `ValidationPipe` in main.ts with:
+- `whitelist: true` - Strip non-whitelisted properties
+- `forbidNonWhitelisted: true` - Throw on extra properties
+- `transform: true` - Auto-transform to DTO types
 
 ### DTOs
 
 - Always use class-validator decorators
-- Use class-transformer for transformation
-- Extend with PartialType/PickType/OmitType for variants
+- `PartialType`, `PickType`, `OmitType` for variants
+- Combine with Swagger decorators
 
-```typescript
-export class CreateUserDto {
-  @IsEmail()
-  @IsNotEmpty()
-  email: string;
+## Authentication
 
-  @IsString()
-  @MinLength(8)
-  password: string;
-
-  @IsString()
-  @IsOptional()
-  name?: string;
-}
-
-export class UpdateUserDto extends PartialType(CreateUserDto) {}
-```
+- Passport.js + JWT strategy
+- Global `JwtAuthGuard` with `@Public()` decorator for exceptions
+- `@CurrentUser()` decorator for accessing user
 
 ## Commands
 
 ```bash
-# Development
-npm run start:dev
-
-# Build
-npm run build
-
-# Tests
-npm run test              # Unit tests
-npm run test:watch        # Watch mode
-npm run test:cov          # Coverage
-npm run test:e2e          # E2E tests
-
-# Linting
-npm run lint
-npm run format
-```
-
-## Global Setup (main.ts)
-
-```typescript
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-
-  // Global validation pipe
-  app.useGlobalPipes(
-    new ValidationPipe({
-      whitelist: true,
-      forbidNonWhitelisted: true,
-      transform: true,
-      transformOptions: {
-        enableImplicitConversion: true,
-      },
-    }),
-  );
-
-  // Global prefix
-  app.setGlobalPrefix('api/v1');
-
-  // CORS
-  app.enableCors();
-
-  // Swagger (dev only)
-  if (process.env.NODE_ENV !== 'production') {
-    const config = new DocumentBuilder()
-      .setTitle('API')
-      .setVersion('1.0')
-      .addBearerAuth()
-      .build();
-    const document = SwaggerModule.createDocument(app, config);
-    SwaggerModule.setup('docs', app, document);
-  }
-
-  await app.listen(process.env.PORT ?? 3000);
-}
-```
-
-## Common Patterns
-
-### Custom Decorator
-
-```typescript
-// current-user.decorator.ts
-export const CurrentUser = createParamDecorator(
-  (data: keyof User | undefined, ctx: ExecutionContext) => {
-    const request = ctx.switchToHttp().getRequest();
-    const user = request.user;
-    return data ? user?.[data] : user;
-  },
-);
-
-// Usage
-@Get('profile')
-getProfile(@CurrentUser() user: User) { ... }
+npm run start:dev       # Dev with watch
+npm run build           # Production build
+npm run test            # Unit tests
+npm run test:e2e        # E2E tests
+npm run test:cov        # Coverage
 ```
 
-### Global Exception Filter
-
-```typescript
-@Catch()
-export class AllExceptionsFilter implements ExceptionFilter {
-  catch(exception: unknown, host: ArgumentsHost) {
-    const ctx = host.switchToHttp();
-    const response = ctx.getResponse<Response>();
-
-    const status =
-      exception instanceof HttpException
-        ? exception.getStatus()
-        : HttpStatus.INTERNAL_SERVER_ERROR;
-
-    const message =
-      exception instanceof HttpException
-        ? exception.message
-        : 'Internal server error';
-
-    response.status(status).json({
-      statusCode: status,
-      message,
-      timestamp: new Date().toISOString(),
-    });
-  }
-}
-```
-
-### Response Interceptor
+## Code Style
 
-```typescript
-@Injectable()
-export class TransformInterceptor<T>
-  implements NestInterceptor<T, Response<T>>
-{
-  intercept(
-    context: ExecutionContext,
-    next: CallHandler,
-  ): Observable<Response<T>> {
-    return next.handle().pipe(
-      map((data) => ({
-        success: true,
-        data,
-      })),
-    );
-  }
-}
-```
+- Constructor injection (not property injection)
+- `readonly` for injected dependencies
+- Async methods return `Promise<T>`
+- Use `ParseUUIDPipe`, `ParseIntPipe` for params

package/configs/nextjs/.claude/rules/api-routes.md

@@ -0,0 +1,358 @@
+---
+paths:
+  - "app/api/**/*.ts"
+  - "src/app/api/**/*.ts"
+---
+
+# Next.js API Routes (App Router)
+
+## Basic Route Handler
+
+```typescript
+// app/api/users/route.ts
+import { NextResponse } from 'next/server';
+
+export async function GET() {
+  const users = await db.user.findMany();
+  return NextResponse.json(users);
+}
+
+export async function POST(request: Request) {
+  const body = await request.json();
+  const user = await db.user.create({ data: body });
+  return NextResponse.json(user, { status: 201 });
+}
+```
+
+## Dynamic Routes
+
+```typescript
+// app/api/users/[id]/route.ts
+import { NextResponse } from 'next/server';
+
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  const user = await db.user.findUnique({ where: { id } });
+
+  if (!user) {
+    return NextResponse.json(
+      { error: 'User not found' },
+      { status: 404 }
+    );
+  }
+
+  return NextResponse.json(user);
+}
+
+export async function PUT(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  const body = await request.json();
+
+  const user = await db.user.update({
+    where: { id },
+    data: body,
+  });
+
+  return NextResponse.json(user);
+}
+
+export async function DELETE(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  await db.user.delete({ where: { id } });
+  return new NextResponse(null, { status: 204 });
+}
+```
+
+## Request Handling
+
+### Query Parameters
+
+```typescript
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const page = parseInt(searchParams.get('page') || '1');
+  const limit = parseInt(searchParams.get('limit') || '10');
+  const search = searchParams.get('search') || '';
+
+  const users = await db.user.findMany({
+    where: { name: { contains: search } },
+    skip: (page - 1) * limit,
+    take: limit,
+  });
+
+  const total = await db.user.count({
+    where: { name: { contains: search } },
+  });
+
+  return NextResponse.json({
+    data: users,
+    meta: {
+      page,
+      limit,
+      total,
+      totalPages: Math.ceil(total / limit),
+    },
+  });
+}
+```
+
+### Headers & Cookies
+
+```typescript
+import { cookies, headers } from 'next/headers';
+
+export async function GET() {
+  const headersList = await headers();
+  const authHeader = headersList.get('authorization');
+
+  const cookieStore = await cookies();
+  const token = cookieStore.get('token');
+
+  return NextResponse.json({ auth: !!authHeader, hasToken: !!token });
+}
+
+export async function POST() {
+  const response = NextResponse.json({ success: true });
+
+  // Set cookie
+  response.cookies.set('session', 'value', {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'lax',
+    maxAge: 60 * 60 * 24 * 7, // 1 week
+  });
+
+  return response;
+}
+```
+
+## Validation with Zod
+
+```typescript
+// app/api/users/route.ts
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2).max(100),
+  age: z.number().min(18).optional(),
+});
+
+export async function POST(request: Request) {
+  const body = await request.json();
+
+  const result = createUserSchema.safeParse(body);
+
+  if (!result.success) {
+    return NextResponse.json(
+      {
+        type: 'validation_error',
+        title: 'Validation Error',
+        status: 400,
+        errors: result.error.issues.map(issue => ({
+          field: issue.path.join('.'),
+          message: issue.message,
+        })),
+      },
+      { status: 400 }
+    );
+  }
+
+  const user = await db.user.create({ data: result.data });
+  return NextResponse.json(user, { status: 201 });
+}
+```
+
+## Error Handling
+
+```typescript
+// lib/api-error.ts
+export class ApiError extends Error {
+  constructor(
+    public status: number,
+    message: string,
+    public code?: string
+  ) {
+    super(message);
+  }
+}
+
+// app/api/users/[id]/route.ts
+import { ApiError } from '@/lib/api-error';
+
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params;
+    const user = await db.user.findUnique({ where: { id } });
+
+    if (!user) {
+      throw new ApiError(404, 'User not found', 'USER_NOT_FOUND');
+    }
+
+    return NextResponse.json(user);
+  } catch (error) {
+    if (error instanceof ApiError) {
+      return NextResponse.json(
+        {
+          type: `https://api.example.com/errors/${error.code}`,
+          title: error.message,
+          status: error.status,
+        },
+        { status: error.status }
+      );
+    }
+
+    console.error('Unexpected error:', error);
+    return NextResponse.json(
+      { title: 'Internal Server Error', status: 500 },
+      { status: 500 }
+    );
+  }
+}
+```
+
+## Authentication
+
+```typescript
+import { auth } from '@/auth';
+
+export async function GET() {
+  const session = await auth();
+
+  if (!session) {
+    return NextResponse.json(
+      { error: 'Unauthorized' },
+      { status: 401 }
+    );
+  }
+
+  const users = await db.user.findMany({
+    where: { organizationId: session.user.organizationId },
+  });
+
+  return NextResponse.json(users);
+}
+```
+
+## File Upload
+
+```typescript
+// app/api/upload/route.ts
+import { writeFile } from 'fs/promises';
+import { NextResponse } from 'next/server';
+
+export async function POST(request: Request) {
+  const formData = await request.formData();
+  const file = formData.get('file') as File | null;
+
+  if (!file) {
+    return NextResponse.json(
+      { error: 'No file uploaded' },
+      { status: 400 }
+    );
+  }
+
+  // Validate file
+  const maxSize = 5 * 1024 * 1024; // 5MB
+  if (file.size > maxSize) {
+    return NextResponse.json(
+      { error: 'File too large' },
+      { status: 400 }
+    );
+  }
+
+  const allowedTypes = ['image/jpeg', 'image/png', 'image/webp'];
+  if (!allowedTypes.includes(file.type)) {
+    return NextResponse.json(
+      { error: 'Invalid file type' },
+      { status: 400 }
+    );
+  }
+
+  const bytes = await file.arrayBuffer();
+  const buffer = Buffer.from(bytes);
+
+  const filename = `${Date.now()}-${file.name}`;
+  await writeFile(`./public/uploads/${filename}`, buffer);
+
+  return NextResponse.json({ url: `/uploads/${filename}` });
+}
+```
+
+## Streaming Response
+
+```typescript
+export async function GET() {
+  const encoder = new TextEncoder();
+
+  const stream = new ReadableStream({
+    async start(controller) {
+      for (let i = 0; i < 10; i++) {
+        controller.enqueue(encoder.encode(`data: ${i}\n\n`));
+        await new Promise(resolve => setTimeout(resolve, 1000));
+      }
+      controller.close();
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+    },
+  });
+}
+```
+
+## Route Configuration
+
+```typescript
+// Caching
+export const revalidate = 60; // Revalidate every 60 seconds
+export const dynamic = 'force-dynamic'; // Always dynamic
+
+// Runtime
+export const runtime = 'edge'; // or 'nodejs'
+
+// Max duration (Vercel)
+export const maxDuration = 30;
+```
+
+## Anti-patterns
+
+```typescript
+// BAD: Not validating input
+export async function POST(request: Request) {
+  const body = await request.json();
+  await db.user.create({ data: body }); // SQL injection risk!
+}
+
+// GOOD: Validate with Zod
+const result = schema.safeParse(body);
+if (!result.success) return errorResponse(result.error);
+
+// BAD: Exposing internal errors
+catch (error) {
+  return NextResponse.json({ error: error.message }); // Leaks info!
+}
+
+// GOOD: Generic error message
+catch (error) {
+  console.error(error);
+  return NextResponse.json({ error: 'Internal error' }, { status: 500 });
+}
+```