claudient 0.1.0

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

@@ -0,0 +1,222 @@
+> 🇩🇪 Dies ist die deutsche Übersetzung. [Englische Version](../nextjs.md).
+
+# Next.js Skill
+
+## Wann aktivieren
+- Eine Next.js-Anwendung mit dem App Router bauen
+- Zwischen Server Components und Client Components entscheiden
+- Server Actions für Formularübermittlungen und Mutationen schreiben
+- Route Handler einrichten (API-Endpunkte im App Router)
+- Authentifizierung mit NextAuth oder einem JWT-Muster implementieren
+- Middleware für Weiterleitungen und Auth Guards konfigurieren
+- Datenabruf mit React `cache()` und `unstable_cache` optimieren
+- Parallele Routes, abfangende Routes oder Route Groups verwenden
+
+## Wann NICHT verwenden
+- Pages Router-Projekte — die Muster unterscheiden sich erheblich
+- Reine SPAs ohne Server-Rendering (Vite + React verwenden)
+- NestJS oder Express-Backends — NestJS Skill verwenden
+- Statische Seiten ohne dynamische Daten (Astro verwenden)
+
+## Anweisungen
+
+### App Router Verzeichnisstruktur
+```
+app/
+├── (auth)/              # Route-Gruppe — kein URL-Segment
+│   ├── login/
+│   │   └── page.tsx
+│   └── layout.tsx       # Auth-spezifisches Layout
+├── (dashboard)/
+│   ├── dashboard/
+│   │   ├── page.tsx     # Server Component standardmäßig
+│   │   └── loading.tsx  # Suspense-Grenze UI
+│   └── layout.tsx
+├── api/
+│   └── webhooks/
+│       └── stripe/
+│           └── route.ts # Route Handler
+├── layout.tsx           # Root-Layout (erforderlich)
+└── page.tsx             # Startseite
+components/
+├── ui/                  # Präsentational (kann Server oder Client sein)
+└── forms/               # Immer Client Components (useState/Events)
+lib/
+├── auth.ts
+├── db.ts
+└── actions/             # Server Actions
+    └── user.ts
+```
+
+### Server vs. Client Components
+```tsx
+// Server Component (Standard) — läuft auf dem Server, wird nie an den Client gesendet
+// Kann: await fetch, DB lesen, Umgebungsvariablen abrufen
+// Kann nicht: useState, useEffect, Browser-APIs, Event-Handler
+export default async function UserProfile({ id }: { id: string }) {
+  const user = await db.user.findUnique({ where: { id } })
+  return <div>{user.name}</div>
+}
+
+// Client Component — 'use client'-Direktive hinzufügen
+'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>
+}
+```
+
+Regel: standardmäßig Server Components verwenden. `'use client'` nur hinzufügen, wenn Interaktivität, Browser-APIs oder React-Hooks benötigt werden.
+
+### Datenabruf-Muster
+```tsx
+// Server Component — direktes async/await, kein useEffect, kein 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>
+}
+
+// Deduplizierung — React cache() umschließt eine Funktion, sodass mehrere Komponenten
+// bei einem Render einen gemeinsamen Fetch teilen
+import { cache } from 'react'
+export const getUser = cache(async (id: string) => {
+  return db.user.findUnique({ where: { id } })
+})
+
+// Statische Generierung mit Revalidierung
+async function getProducts() {
+  const res = await fetch('https://api.example.com/products', {
+    next: { revalidate: 3600 }, // ISR — stündlich revalidieren
+  })
+  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 }
+}
+
+// In einer 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 Handler
+```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 (Root-Ebene)
+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*'],
+}
+```
+
+### Parallele und abfangende Routes
+```
+app/
+├── @modal/          # Parallele Route — wird neben dem Hauptinhalt gerendert
+│   └── (.)photo/    # Abfangende Route — fängt /photo/[id] ab
+│       └── [id]/
+│           └── page.tsx
+├── photo/
+│   └── [id]/
+│       └── page.tsx
+└── layout.tsx       # Akzeptiert { children, modal } als Props
+```
+
+### Fehler- und Lade-Grenzen
+```tsx
+// app/dashboard/loading.tsx — während Suspense angezeigt
+export default function Loading() {
+  return <DashboardSkeleton />
+}
+
+// app/dashboard/error.tsx — Fehlergrenze für dieses 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>
+  )
+}
+```
+
+### Umgebungsvariablen
+- `NEXT_PUBLIC_*` — dem Browser ausgesetzt
+- Alle anderen — nur serverseitig (in Client Components nie zugänglich)
+- Niemals eine server-only Umgebungsvariable in einer Client Component importieren — sie gibt `undefined` zurück
+
+## Beispiel
+
+**Benutzer:** Eine paginierte Blog-Posts-Seite bei `/blog` hinzufügen, die aus PostgreSQL abruft, mit einem "Neuer Post"-Modal, das bei `/blog/new` öffnet, aber nicht von der Posts-Liste wegnavigiert.
+
+**Erwartete Ausgabe:**
+- `app/blog/page.tsx` — Server Component, ruft Posts mit `db.post.findMany` ab, rendert `<PostList>` + `<Link href="/blog/new">`
+- `app/@modal/(.)blog/new/page.tsx` — Abfangende Route zeigt eine `<NewPostModal>` Client Component
+- `app/blog/new/page.tsx` — Vollseiten-Fallback für direkte Navigation
+- `app/layout.tsx` — Aktualisiert, um `modal`-Parallele-Route-Slot zu akzeptieren und neben `children` zu rendern
+- `lib/actions/post.ts` — `createPost` Server Action mit Zod-Validierung + `revalidatePath('/blog')`
+
+---
+
+> **Mit uns arbeiten:** Claudient wird von [Uitbreiden](https://uitbreiden.com/) unterstützt — wir bauen KI-Produkte und B2B-Lösungen mit Entwickler-Communities. [uitbreiden.com](https://uitbreiden.com/)

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

@@ -0,0 +1,274 @@
+> 🇪🇸 Esta es la traducción en español. [Versión en inglés](../nestjs.md).
+
+# Skill de NestJS
+
+## Cuándo activar
+- Construir una aplicación NestJS (módulos, controladores, servicios)
+- Configurar guards, interceptores, pipes y filtros de excepciones
+- Integrar TypeORM o Prisma con NestJS
+- Implementar CQRS con comandos, queries y eventos
+- Configurar microservicios (transporte TCP, Redis, RabbitMQ)
+- Escribir pruebas unitarias y e2e con Jest y Supertest
+- Generar documentación OpenAPI con `@nestjs/swagger`
+
+## Cuándo NO usar
+- Rutas de API de Next.js o Fastify standalone — framework diferente
+- Scripts simples de Express — la sobrecarga de NestJS no está justificada
+- Funciones Lambda donde el tiempo de arranque en frío es crítico
+
+## Instrucciones
+
+### Estructura del módulo
+```
+src/
+├── app.module.ts           # Módulo raíz
+├── main.ts                 # Bootstrap
+├── common/
+│   ├── decorators/
+│   ├── filters/
+│   ├── guards/
+│   ├── interceptors/
+│   └── pipes/
+├── config/
+│   └── configuration.ts   # Configuración de 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,       // eliminar campos desconocidos
+    forbidNonWhitelisted: true,
+    transform: true,       // auto-transformar payloads a clases 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()
+```
+
+### Módulo, Controlador, Servicio
+```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 con 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))
+  }
+}
+```
+
+### Interceptores
+```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
+// Instalar: @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
+  }
+}
+
+// En servicio/controlador:
+const user = await this.commandBus.execute(new CreateUserCommand(dto))
+```
+
+### Testing
+```ts
+// Prueba unitaria
+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)
+  })
+})
+
+// Prueba E2E
+describe('POST /users', () => {
+  it('creates a user', () => {
+    return request(app.getHttpServer())
+      .post('/users')
+      .send({ email: 'a@b.com', password: 'password123' })
+      .expect(201)
+  })
+})
+```
+
+## Ejemplo
+
+**Usuario:** Agregar un módulo `Products` a una aplicación NestJS con TypeORM, incluyendo endpoints CRUD, eliminación solo para admin protegida por `RolesGuard` y documentación OpenAPI.
+
+**Salida esperada:**
+- `products.entity.ts` — entidad TypeORM con `id` (UUID), `name`, `price` (decimal), `stock`, `createdAt`
+- `dto/create-product.dto.ts` — DTO class-validator con decoradores `@ApiProperty`
+- `products.service.ts` — métodos CRUD usando `Repository<Product>`, lanzando `NotFoundException` en caso de ausencia
+- `products.controller.ts` — todos los endpoints CRUD, `@UseGuards(JwtAuthGuard, RolesGuard)` + `@Roles(Role.Admin)` en `DELETE`
+- `products.module.ts` — importa `TypeOrmModule.forFeature([Product])`
+
+---
+
+> **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/)