claudient 0.1.0

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

@@ -0,0 +1,222 @@
+> 🇪🇸 Esta es la traducción en español. [Versión en inglés](../nextjs.md).
+
+# Skill de Next.js
+
+## Cuándo activar
+- Construir una aplicación Next.js usando el App Router
+- Decidir entre Server Components y Client Components
+- Escribir Server Actions para envíos de formularios y mutations
+- Configurar route handlers (endpoints de API en App Router)
+- Implementar autenticación con NextAuth o un patrón JWT
+- Configurar middleware para redirecciones y guardas de autenticación
+- Optimizar la obtención de datos con `cache()` y `unstable_cache` de React
+- Usar rutas paralelas, rutas interceptadas o grupos de rutas
+
+## Cuándo NO usar
+- Proyectos con Pages Router — los patrones difieren significativamente
+- SPAs puras sin renderizado en servidor (usar Vite + React)
+- Backends NestJS o Express — usar el skill de NestJS
+- Sitios estáticos sin datos dinámicos (usar Astro)
+
+## Instrucciones
+
+### Estructura de directorios del App Router
+```
+app/
+├── (auth)/              # Grupo de rutas — sin segmento de URL
+│   ├── login/
+│   │   └── page.tsx
+│   └── layout.tsx       # Layout específico de autenticación
+├── (dashboard)/
+│   ├── dashboard/
+│   │   ├── page.tsx     # Server Component por defecto
+│   │   └── loading.tsx  # UI del límite de Suspense
+│   └── layout.tsx
+├── api/
+│   └── webhooks/
+│       └── stripe/
+│           └── route.ts # Route Handler
+├── layout.tsx           # Layout raíz (requerido)
+└── page.tsx             # Página de inicio
+components/
+├── ui/                  # Presentacional (puede ser server o client)
+└── forms/               # Siempre Client Components (useState/eventos)
+lib/
+├── auth.ts
+├── db.ts
+└── actions/             # Server Actions
+    └── user.ts
+```
+
+### Server vs. Client Components
+```tsx
+// Server Component (por defecto) — se ejecuta en el servidor, nunca se envía al cliente
+// Puede: await fetch, leer BD, acceder a variables de entorno
+// No puede: useState, useEffect, APIs del navegador, manejadores de eventos
+export default async function UserProfile({ id }: { id: string }) {
+  const user = await db.user.findUnique({ where: { id } })
+  return <div>{user.name}</div>
+}
+
+// Client Component — agregar directiva '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>
+}
+```
+
+Regla: por defecto usar Server Components. Agregar `'use client'` solo cuando se necesita interactividad, APIs del navegador o hooks de React.
+
+### Patrones de obtención de datos
+```tsx
+// Server Component — async/await directo, sin useEffect, sin 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>
+}
+
+// Deduplicación — React cache() envuelve una función para que múltiples componentes
+// que la llamen en un render compartan una sola fetch
+import { cache } from 'react'
+export const getUser = cache(async (id: string) => {
+  return db.user.findUnique({ where: { id } })
+})
+
+// Generación estática con revalidación
+async function getProducts() {
+  const res = await fetch('https://api.example.com/products', {
+    next: { revalidate: 3600 }, // ISR — revalidar cada hora
+  })
+  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 }
+}
+
+// En 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 (nivel raíz)
+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*'],
+}
+```
+
+### Rutas paralelas e interceptadas
+```
+app/
+├── @modal/          # Ruta paralela — se renderiza junto al contenido principal
+│   └── (.)photo/    # Ruta interceptada — intercepta /photo/[id]
+│       └── [id]/
+│           └── page.tsx
+├── photo/
+│   └── [id]/
+│       └── page.tsx
+└── layout.tsx       # Acepta { children, modal } como props
+```
+
+### Límites de error y carga
+```tsx
+// app/dashboard/loading.tsx — mostrado durante Suspense
+export default function Loading() {
+  return <DashboardSkeleton />
+}
+
+// app/dashboard/error.tsx — límite de error para este segmento
+'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 de entorno
+- `NEXT_PUBLIC_*` — expuestas al navegador
+- Todo lo demás — solo servidor (nunca accesible en Client Components)
+- Nunca importes una variable de entorno solo del servidor dentro de un Client Component — devuelve `undefined` silenciosamente
+
+## Ejemplo
+
+**Usuario:** Agregar una página de publicaciones de blog paginada en `/blog` que obtiene de PostgreSQL, con un modal "Nueva Publicación" que se abre en `/blog/new` pero no navega fuera de la lista de publicaciones.
+
+**Salida esperada:**
+- `app/blog/page.tsx` — Server Component, obtiene posts con `db.post.findMany`, renderiza `<PostList>` + `<Link href="/blog/new">`
+- `app/@modal/(.)blog/new/page.tsx` — Ruta interceptada mostrando un Client Component `<NewPostModal>`
+- `app/blog/new/page.tsx` — Fallback a página completa para navegación directa
+- `app/layout.tsx` — Actualizado para aceptar el slot de ruta paralela `modal` y renderizarlo junto a `children`
+- `lib/actions/post.ts` — Server Action `createPost` con validación Zod + `revalidatePath('/blog')`
+
+---
+
+> **Trabaja con nosotros:** Claudient está respaldado por [Uitbreiden](https://uitbreiden.com/) — construimos productos de IA y soluciones B2B con comunidades de desarrolladores. [uitbreiden.com](https://uitbreiden.com/)

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

@@ -0,0 +1,274 @@
+> 🇫🇷 This is the French translation. [English version](../nestjs.md).
+
+# Compétence NestJS
+
+## Quand activer
+- Construire une application NestJS (modules, controllers, services)
+- Configurer des guards, interceptors, pipes et filtres d'exception
+- Intégrer TypeORM ou Prisma avec NestJS
+- Implémenter CQRS avec des commandes, requêtes et événements
+- Configurer des microservices (transport TCP, Redis, RabbitMQ)
+- Rédiger des tests unitaires et e2e avec Jest et Supertest
+- Générer des docs OpenAPI avec `@nestjs/swagger`
+
+## Quand NE PAS utiliser
+- Routes API Next.js ou Fastify standalone — framework différent
+- Scripts Express simples — le surcoût NestJS n'est pas justifié
+- Fonctions Lambda où le temps de cold start est critique
+
+## Instructions
+
+### Structure des modules
+```
+src/
+├── app.module.ts           # Module racine
+├── main.ts                 # Bootstrap
+├── common/
+│   ├── decorators/
+│   ├── filters/
+│   ├── guards/
+│   ├── interceptors/
+│   └── pipes/
+├── config/
+│   └── configuration.ts   # Configuration du ConfigService
+└── 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,       // supprimer les champs inconnus
+    forbidNonWhitelisted: true,
+    transform: true,       // auto-transformer les payloads en classes DTO
+  }))
+
+  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 avec 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
+// Installer : @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
+  }
+}
+
+// Dans le service/controller :
+const user = await this.commandBus.execute(new CreateUserCommand(dto))
+```
+
+### Tests
+```ts
+// Test unitaire
+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('lève ConflictException pour un email en doublon', async () => {
+    repo.findOneBy.mockResolvedValue(existingUser)
+    await expect(service.create(dto)).rejects.toThrow(ConflictException)
+  })
+})
+
+// Test E2E
+describe('POST /users', () => {
+  it('crée un utilisateur', () => {
+    return request(app.getHttpServer())
+      .post('/users')
+      .send({ email: 'a@b.com', password: 'password123' })
+      .expect(201)
+  })
+})
+```
+
+## Exemple
+
+**Utilisateur :** Ajouter un module `Products` à une application NestJS avec TypeORM, incluant des endpoints CRUD, une suppression réservée aux admins protégée par un `RolesGuard` et des docs OpenAPI.
+
+**Sortie attendue :**
+- `products.entity.ts` — entité TypeORM avec `id` (UUID), `name`, `price` (decimal), `stock`, `createdAt`
+- `dto/create-product.dto.ts` — DTO class-validator avec décorateurs `@ApiProperty`
+- `products.service.ts` — méthodes CRUD utilisant `Repository<Product>`, levant `NotFoundException` si manquant
+- `products.controller.ts` — tous les endpoints CRUD, `@UseGuards(JwtAuthGuard, RolesGuard)` + `@Roles(Role.Admin)` sur `DELETE`
+- `products.module.ts` — importe `TypeOrmModule.forFeature([Product])`
+
+---
+
+> **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/)