claudient 0.1.0

package/skills/backend/nodejs/fr/nextjs.md

@@ -0,0 +1,222 @@
+> 🇫🇷 This is the French translation. [English version](../nextjs.md).
+
+# Compétence Next.js
+
+## Quand activer
+- Construire une application Next.js avec l'App Router
+- Décider entre les Server Components et les Client Components
+- Rédiger des Server Actions pour les soumissions de formulaires et les mutations
+- Configurer des route handlers (endpoints API dans l'App Router)
+- Implémenter l'authentification avec NextAuth ou un pattern JWT
+- Configurer le middleware pour les redirections et les guards d'auth
+- Optimiser la récupération de données avec `cache()` et `unstable_cache` de React
+- Utiliser les routes parallèles, les routes d'interception ou les groupes de routes
+
+## Quand NE PAS utiliser
+- Projets Pages Router — les patterns diffèrent significativement
+- SPAs pures sans rendu serveur (utiliser Vite + React)
+- Backends NestJS ou Express — utiliser la compétence NestJS
+- Sites statiques sans données dynamiques (utiliser Astro)
+
+## Instructions
+
+### Structure des répertoires App Router
+```
+app/
+├── (auth)/              # Groupe de routes — pas de segment URL
+│   ├── login/
+│   │   └── page.tsx
+│   └── layout.tsx       # Layout spécifique à l'auth
+├── (dashboard)/
+│   ├── dashboard/
+│   │   ├── page.tsx     # Server Component par défaut
+│   │   └── loading.tsx  # UI de la boundary Suspense
+│   └── layout.tsx
+├── api/
+│   └── webhooks/
+│       └── stripe/
+│           └── route.ts # Route Handler
+├── layout.tsx           # Layout racine (requis)
+└── page.tsx             # Page d'accueil
+components/
+├── ui/                  # Présentationnels (peuvent être server ou client)
+└── forms/               # Toujours des client components (useState/événements)
+lib/
+├── auth.ts
+├── db.ts
+└── actions/             # Server Actions
+    └── user.ts
+```
+
+### Server Components vs. Client Components
+```tsx
+// Server Component (défaut) — s'exécute sur le serveur, jamais envoyé au client
+// Peut : await fetch, lire la DB, accéder aux variables d'environnement
+// Ne peut pas : useState, useEffect, APIs navigateur, gestionnaires d'événements
+export default async function UserProfile({ id }: { id: string }) {
+  const user = await db.user.findUnique({ where: { id } })
+  return <div>{user.name}</div>
+}
+
+// Client Component — ajouter la directive 'use client'
+'use client'
+import { useState } from 'react'
+
+export function LikeButton({ initialCount }: { initialCount: number }) {
+  const [count, setCount] = useState(initialCount)
+  return <button onClick={() => setCount(c => c + 1)}>{count} likes</button>
+}
+```
+
+Règle : par défaut Server Components. Ajouter `'use client'` uniquement quand vous avez besoin d'interactivité, d'APIs navigateur ou de hooks React.
+
+### Patterns de récupération de données
+```tsx
+// Server Component — async/await direct, pas de useEffect, pas de useState
+export default async function PostList() {
+  const posts = await db.post.findMany({ where: { published: true } })
+  return <ul>{posts.map(p => <li key={p.id}>{p.title}</li>)}</ul>
+}
+
+// Déduplication — React cache() enveloppe une fonction pour que plusieurs composants
+// l'appelant dans un même rendu partagent une seule requête
+import { cache } from 'react'
+export const getUser = cache(async (id: string) => {
+  return db.user.findUnique({ where: { id } })
+})
+
+// Génération statique avec revalidation
+async function getProducts() {
+  const res = await fetch('https://api.example.com/products', {
+    next: { revalidate: 3600 }, // ISR — revalider toutes les heures
+  })
+  return res.json()
+}
+```
+
+### Server Actions
+```tsx
+// lib/actions/user.ts
+'use server'
+import { revalidatePath } from 'next/cache'
+import { z } from 'zod'
+
+const UpdateSchema = z.object({
+  name: z.string().min(1),
+})
+
+export async function updateUser(formData: FormData) {
+  const parsed = UpdateSchema.safeParse({ name: formData.get('name') })
+  if (!parsed.success) return { error: parsed.error.flatten() }
+
+  await db.user.update({ where: { id: getCurrentUserId() }, data: parsed.data })
+  revalidatePath('/dashboard/profile')
+  return { success: true }
+}
+
+// Dans un Server Component :
+export default function ProfileForm({ user }: { user: User }) {
+  return (
+    <form action={updateUser}>
+      <input name="name" defaultValue={user.name} />
+      <button type="submit">Save</button>
+    </form>
+  )
+}
+```
+
+### Route Handlers
+```ts
+// app/api/webhooks/stripe/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+import Stripe from 'stripe'
+
+export async function POST(req: NextRequest) {
+  const body = await req.text()
+  const sig = req.headers.get('stripe-signature')!
+
+  let event: Stripe.Event
+  try {
+    event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!)
+  } catch {
+    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 })
+  }
+
+  if (event.type === 'checkout.session.completed') {
+    await handleCheckoutCompleted(event.data.object)
+  }
+
+  return NextResponse.json({ received: true })
+}
+```
+
+### Middleware
+```ts
+// middleware.ts (au niveau racine)
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export function middleware(request: NextRequest) {
+  const token = request.cookies.get('auth-token')
+  if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/login', request.url))
+  }
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/api/protected/:path*'],
+}
+```
+
+### Routes parallèles et d'interception
+```
+app/
+├── @modal/          # Route parallèle — s'affiche à côté du contenu principal
+│   └── (.)photo/    # Route d'interception — intercepte /photo/[id]
+│       └── [id]/
+│           └── page.tsx
+├── photo/
+│   └── [id]/
+│       └── page.tsx
+└── layout.tsx       # Accepte { children, modal } comme props
+```
+
+### Boundaries d'erreur et de chargement
+```tsx
+// app/dashboard/loading.tsx — affiché pendant Suspense
+export default function Loading() {
+  return <DashboardSkeleton />
+}
+
+// app/dashboard/error.tsx — boundary d'erreur pour ce segment
+'use client'
+export default function Error({ error, reset }: { error: Error; reset: () => void }) {
+  return (
+    <div>
+      <p>{error.message}</p>
+      <button onClick={reset}>Retry</button>
+    </div>
+  )
+}
+```
+
+### Variables d'environnement
+- `NEXT_PUBLIC_*` — exposées au navigateur
+- Toutes les autres — côté serveur uniquement (jamais accessibles dans les Client Components)
+- Ne jamais importer une variable d'environnement server-only dans un Client Component — elle retourne `undefined` silencieusement
+
+## Exemple
+
+**Utilisateur :** Ajouter une page de blog paginée à `/blog` qui récupère depuis PostgreSQL, avec une modale "Nouvel article" qui s'ouvre à `/blog/new` sans naviguer hors de la liste des articles.
+
+**Sortie attendue :**
+- `app/blog/page.tsx` — Server Component, récupère les articles avec `db.post.findMany`, affiche `<PostList>` + `<Link href="/blog/new">`
+- `app/@modal/(.)blog/new/page.tsx` — Route d'interception affichant un Client Component `<NewPostModal>`
+- `app/blog/new/page.tsx` — Page de repli pour la navigation directe
+- `app/layout.tsx` — Mis à jour pour accepter le slot `modal` de la route parallèle et l'afficher aux côtés de `children`
+- `lib/actions/post.ts` — Server Action `createPost` avec validation Zod + `revalidatePath('/blog')`
+
+---
+
+> **Travaillez avec nous :** Claudient est soutenu par [Uitbreiden](https://uitbreiden.com/) — nous construisons des produits IA et des solutions B2B avec des communautés de développeurs. [uitbreiden.com](https://uitbreiden.com/)

package/skills/backend/nodejs/nestjs.md

@@ -0,0 +1,272 @@
+# NestJS Skill
+
+## When to activate
+- Building a NestJS application (modules, controllers, services)
+- Setting up guards, interceptors, pipes, and exception filters
+- Integrating TypeORM or Prisma with NestJS
+- Implementing CQRS with commands, queries, and events
+- Setting up microservices (TCP, Redis, RabbitMQ transport)
+- Writing unit and e2e tests with Jest and Supertest
+- Generating OpenAPI docs with `@nestjs/swagger`
+
+## When NOT to use
+- Next.js API routes or Fastify standalone — different framework
+- Simple Express scripts — NestJS overhead isn't justified
+- Lambda functions where cold start time is critical
+
+## Instructions
+
+### Module structure
+```
+src/
+├── app.module.ts           # Root module
+├── main.ts                 # Bootstrap
+├── common/
+│   ├── decorators/
+│   ├── filters/
+│   ├── guards/
+│   ├── interceptors/
+│   └── pipes/
+├── config/
+│   └── configuration.ts   # ConfigService setup
+└── 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.service.spec.ts
+```
+
+### Bootstrap
+```ts
+// main.ts
+import { NestFactory } from '@nestjs/core'
+import { AppModule } from './app.module'
+import { ValidationPipe } from '@nestjs/common'
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger'
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule)
+
+  app.useGlobalPipes(new ValidationPipe({
+    whitelist: true,       // strip unknown fields
+    forbidNonWhitelisted: true,
+    transform: true,       // auto-transform payloads to DTO classes
+  }))
+
+  const config = new DocumentBuilder()
+    .setTitle('API')
+    .setVersion('1.0')
+    .addBearerAuth()
+    .build()
+  SwaggerModule.setup('docs', app, SwaggerModule.createDocument(app, config))
+
+  await app.listen(3000)
+}
+bootstrap()
+```
+
+### Module, Controller, Service
+```ts
+// users.module.ts
+@Module({
+  imports: [TypeOrmModule.forFeature([User]), JwtModule.register({})],
+  controllers: [UsersController],
+  providers: [UsersService],
+  exports: [UsersService],
+})
+export class UsersModule {}
+
+// users.controller.ts
+@ApiTags('users')
+@ApiBearerAuth()
+@UseGuards(JwtAuthGuard)
+@Controller('users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Post()
+  @HttpCode(HttpStatus.CREATED)
+  create(@Body() dto: CreateUserDto): Promise<UserResponseDto> {
+    return this.usersService.create(dto)
+  }
+
+  @Get(':id')
+  findOne(@Param('id', ParseUUIDPipe) id: string): Promise<UserResponseDto> {
+    return this.usersService.findOneOrFail(id)
+  }
+}
+
+// users.service.ts
+@Injectable()
+export class UsersService {
+  constructor(
+    @InjectRepository(User)
+    private readonly userRepo: Repository<User>,
+  ) {}
+
+  async create(dto: CreateUserDto): Promise<User> {
+    const exists = await this.userRepo.findOneBy({ email: dto.email })
+    if (exists) throw new ConflictException('Email already in use')
+    const user = this.userRepo.create({
+      ...dto,
+      password: await bcrypt.hash(dto.password, 10),
+    })
+    return this.userRepo.save(user)
+  }
+
+  async findOneOrFail(id: string): Promise<User> {
+    const user = await this.userRepo.findOneBy({ id })
+    if (!user) throw new NotFoundException(`User ${id} not found`)
+    return user
+  }
+}
+```
+
+### DTOs with class-validator
+```ts
+// dto/create-user.dto.ts
+import { IsEmail, IsString, MinLength, IsOptional } from 'class-validator'
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger'
+
+export class CreateUserDto {
+  @ApiProperty({ example: 'user@example.com' })
+  @IsEmail()
+  email: string
+
+  @ApiProperty({ minLength: 8 })
+  @IsString()
+  @MinLength(8)
+  password: string
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  name?: string
+}
+```
+
+### Guards
+```ts
+// common/guards/jwt-auth.guard.ts
+@Injectable()
+export class JwtAuthGuard extends AuthGuard('jwt') {
+  handleRequest<T>(err: Error, user: T, info: Error): T {
+    if (err || !user) {
+      throw err || new UnauthorizedException(info?.message)
+    }
+    return user
+  }
+}
+
+// common/guards/roles.guard.ts
+@Injectable()
+export class RolesGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const roles = this.reflector.getAllAndOverride<Role[]>('roles', [
+      context.getHandler(),
+      context.getClass(),
+    ])
+    if (!roles) return true
+    const { user } = context.switchToHttp().getRequest()
+    return roles.some(role => user.roles?.includes(role))
+  }
+}
+```
+
+### Interceptors
+```ts
+// common/interceptors/transform.interceptor.ts
+@Injectable()
+export class TransformInterceptor<T>
+  implements NestInterceptor<T, { data: T; timestamp: string }>
+{
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    return next.handle().pipe(
+      map(data => ({ data, timestamp: new Date().toISOString() }))
+    )
+  }
+}
+```
+
+### CQRS
+```ts
+// Install: @nestjs/cqrs
+
+// commands/create-user.command.ts
+export class CreateUserCommand {
+  constructor(public readonly dto: CreateUserDto) {}
+}
+
+// commands/create-user.handler.ts
+@CommandHandler(CreateUserCommand)
+export class CreateUserHandler implements ICommandHandler<CreateUserCommand> {
+  constructor(private readonly userRepo: UserRepository) {}
+
+  async execute(command: CreateUserCommand): Promise<User> {
+    const user = User.create(command.dto)
+    await this.userRepo.save(user)
+    return user
+  }
+}
+
+// In service/controller:
+const user = await this.commandBus.execute(new CreateUserCommand(dto))
+```
+
+### Testing
+```ts
+// Unit test
+describe('UsersService', () => {
+  let service: UsersService
+  let repo: jest.Mocked<Repository<User>>
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [
+        UsersService,
+        { provide: getRepositoryToken(User), useValue: createMockRepository() },
+      ],
+    }).compile()
+    service = module.get(UsersService)
+    repo = module.get(getRepositoryToken(User))
+  })
+
+  it('throws ConflictException for duplicate email', async () => {
+    repo.findOneBy.mockResolvedValue(existingUser)
+    await expect(service.create(dto)).rejects.toThrow(ConflictException)
+  })
+})
+
+// E2E test
+describe('POST /users', () => {
+  it('creates a user', () => {
+    return request(app.getHttpServer())
+      .post('/users')
+      .send({ email: 'a@b.com', password: 'password123' })
+      .expect(201)
+  })
+})
+```
+
+## Example
+
+**User:** Add a `Products` module to a NestJS app with TypeORM, including CRUD endpoints, admin-only delete protected by a `RolesGuard`, and OpenAPI docs.
+
+**Expected output:**
+- `products.entity.ts` — TypeORM entity with `id` (UUID), `name`, `price` (decimal), `stock`, `createdAt`
+- `dto/create-product.dto.ts` — class-validator DTO with `@ApiProperty` decorators
+- `products.service.ts` — CRUD methods using `Repository<Product>`, throwing `NotFoundException` on missing
+- `products.controller.ts` — all CRUD endpoints, `@UseGuards(JwtAuthGuard, RolesGuard)` + `@Roles(Role.Admin)` on `DELETE`
+- `products.module.ts` — imports `TypeOrmModule.forFeature([Product])`
+
+---
+
+> **Work with us:** Claudient is backed by [Uitbreiden](https://uitbreiden.com/) — we build AI products and B2B solutions with developer communities. [uitbreiden.com](https://uitbreiden.com/)