@malamute/ai-rules 1.0.0

package/configs/nestjs/CLAUDE.md

@@ -0,0 +1,263 @@
+# NestJS Project Guidelines
+
+@../_shared/CLAUDE.md
+
+## Stack
+
+- NestJS 10+ (latest stable)
+- TypeScript strict mode
+- Node.js 20+
+- Jest for testing
+- Supertest for E2E
+
+## Architecture
+
+### Modular Monolith (Recommended)
+
+```
+src/
+├── modules/
+│   ├── users/
+│   │   ├── users.module.ts
+│   │   ├── users.controller.ts
+│   │   ├── users.service.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]/
+│       └── ...
+│
+├── 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
+
+## Code Style
+
+### Controllers
+
+- Handle HTTP concerns only (request/response)
+- Delegate business logic to services
+- Use DTOs for all inputs
+- Return consistent response shapes
+
+```typescript
+@Controller('users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Post()
+  @HttpCode(HttpStatus.CREATED)
+  create(@Body() createUserDto: CreateUserDto): Promise<User> {
+    return this.usersService.create(createUserDto);
+  }
+
+  @Get(':id')
+  findOne(@Param('id', ParseUUIDPipe) id: string): Promise<User> {
+    return this.usersService.findOne(id);
+  }
+}
+```
+
+### Services
+
+- Contain all business logic
+- Inject repositories/other services
+- Throw appropriate NestJS exceptions
+
+```typescript
+@Injectable()
+export class UsersService {
+  constructor(private readonly usersRepository: UsersRepository) {}
+
+  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;
+  }
+}
+```
+
+### DTOs
+
+- Always use class-validator decorators
+- Use class-transformer for transformation
+- Extend with PartialType/PickType/OmitType for variants
+
+```typescript
+export class CreateUserDto {
+  @IsEmail()
+  @IsNotEmpty()
+  email: string;
+
+  @IsString()
+  @MinLength(8)
+  password: string;
+
+  @IsString()
+  @IsOptional()
+  name?: string;
+}
+
+export class UpdateUserDto extends PartialType(CreateUserDto) {}
+```
+
+## 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) { ... }
+```
+
+### 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
+
+```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,
+      })),
+    );
+  }
+}
+```

package/configs/nextjs/.claude/rules/components.md

@@ -0,0 +1,211 @@
+---
+paths:
+  - "apps/**/*.tsx"
+  - "libs/**/*.tsx"
+---
+
+# Component Rules (Next.js 15 / React 19)
+
+## Server vs Client Components
+
+### Server Components (Default)
+
+No directive needed. Use for:
+- Data fetching
+- Database access
+- Accessing secrets/environment variables
+- Heavy dependencies that don't need to ship to client
+
+```tsx
+// app/users/page.tsx
+// This is a Server Component by default
+import { db } from '@/lib/db';
+
+export default async function UsersPage() {
+  const users = await db.user.findMany();
+
+  return (
+    <ul>
+      {users.map((user) => (
+        <li key={user.id}>{user.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Client Components
+
+Add `'use client'` at the top. Use for:
+- Interactivity (onClick, onChange, etc.)
+- React hooks (useState, useEffect, useContext)
+- Browser APIs (localStorage, window, etc.)
+
+```tsx
+'use client';
+
+import { useState } from 'react';
+
+export function Counter() {
+  const [count, setCount] = useState(0);
+
+  return (
+    <button onClick={() => setCount(count + 1)}>
+      Count: {count}
+    </button>
+  );
+}
+```
+
+### Decision Tree
+
+```
+Need hooks or interactivity?
+├── YES → 'use client'
+└── NO → Server Component (default)
+         └── Fetching data? → async component
+```
+
+## Component Patterns
+
+### Props Interface
+
+Always define props interface above component:
+
+```tsx
+interface UserCardProps {
+  user: User;
+  isSelected?: boolean;
+  onSelect: (user: User) => void;
+}
+
+export function UserCard({ user, isSelected = false, onSelect }: UserCardProps) {
+  return (/* ... */);
+}
+```
+
+### Composition over Props
+
+```tsx
+// BAD - prop drilling
+<Card
+  title="User Profile"
+  subtitle="Details"
+  icon={<UserIcon />}
+  footer={<Button>Edit</Button>}
+/>
+
+// GOOD - composition
+<Card>
+  <CardHeader>
+    <UserIcon />
+    <CardTitle>User Profile</CardTitle>
+    <CardDescription>Details</CardDescription>
+  </CardHeader>
+  <CardFooter>
+    <Button>Edit</Button>
+  </CardFooter>
+</Card>
+```
+
+### Async Server Components
+
+```tsx
+// Server Component can be async
+export default async function UsersPage() {
+  const users = await getUsers(); // Direct await
+
+  return <UserList users={users} />;
+}
+```
+
+### Client Component with Server Data
+
+```tsx
+// page.tsx (Server)
+export default async function Page() {
+  const data = await fetchData();
+  return <InteractiveComponent initialData={data} />;
+}
+
+// interactive-component.tsx (Client)
+'use client';
+
+export function InteractiveComponent({ initialData }: Props) {
+  const [data, setData] = useState(initialData);
+  // Can now use hooks with server-fetched data
+}
+```
+
+## File Organization
+
+### Co-located Components
+
+```
+app/
+  users/
+    page.tsx              # Route
+    _components/          # Private folder (underscore prefix)
+      user-list.tsx       # Only used in /users
+      user-card.tsx
+      user-form.tsx
+    actions.ts            # Server Actions
+    loading.tsx           # Loading UI
+    error.tsx             # Error UI
+```
+
+### Shared Components
+
+```
+libs/
+  shared/
+    ui/
+      button.tsx
+      input.tsx
+      card.tsx
+      index.ts            # Barrel export
+```
+
+## Naming Conventions
+
+```tsx
+// Component files: kebab-case
+user-card.tsx
+user-list.tsx
+
+// Components: PascalCase
+export function UserCard() {}
+export function UserList() {}
+
+// Hooks: camelCase with 'use' prefix
+export function useUserData() {}
+
+// Event handlers: handle + Event
+const handleClick = () => {};
+const handleSubmit = () => {};
+const handleUserSelect = (user: User) => {};
+```
+
+## Exports
+
+```tsx
+// Named exports for reusable components
+export function Button() {}
+export function Input() {}
+
+// Default export ONLY for:
+// - page.tsx
+// - layout.tsx
+// - loading.tsx
+// - error.tsx
+// - not-found.tsx
+export default function Page() {}
+```
+
+## Avoid
+
+- `useEffect` for data fetching (use Server Components)
+- Default exports for library components
+- Inline styles (use CSS modules or Tailwind)
+- Anonymous components
+- Props spreading without type safety