claude-code-arcane 1.0.1 → 1.1.1

package/rules/react-perf.md

@@ -0,0 +1,59 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "src/components/**"
+  - "src/hooks/**"
+  - "components/**"
+  - "hooks/**"
+---
+
+# React Performance Rules
+
+Reglas de re-render, rendering y micro-optimización JS para React. Ordenadas por impacto. Catálogo completo (64 reglas) + ejemplos: skill `nextjs-best-practices`.
+
+## HIGH — Estructura de componentes
+
+- **No definir componentes dentro de componentes.** Definir a nivel módulo o extraer; definirlos inline los remonta en cada render (pierde estado, mata performance).
+- **`content-visibility: auto`** para listas largas — difiere render y paint de lo que está off-screen.
+- **`defer`/`async` en `<script>`** para no bloquear el render durante el parsing.
+- **Resource hints de React DOM** (`preload`, `preconnect`, `prefetchDNS`) para recursos críticos.
+
+## MEDIUM — Re-render optimization
+
+- **Calcular derived state durante el render**, no guardarlo en `useState` (se desincroniza y genera renders extra).
+- **Leer state dinámico en el callback**, no suscribirse en render time cuando solo se usa en un handler.
+- **Functional `setState`** (`setX(prev => ...)`) para operar sobre el último valor y crear callbacks estables.
+- **Lazy state init**: pasar función a `useState(() => expensive())` para no recomputar en cada render.
+- **`useTransition` para updates no urgentes**; `useDeferredValue` para mantener inputs responsivos durante cómputo pesado.
+- **`useRef` para valores transitorios** (no-UI) que cambian seguido y no deben disparar render.
+- **Extraer defaults no-primitivos** de componentes memoizados a constantes a nivel módulo (preserva la memoización).
+- **Side effects de interacción van en event handlers**, no en `useEffect`.
+- **Dependencias de effect primitivas y estrechas**, no objetos enteros.
+
+## LOW-MEDIUM — useMemo / JS
+
+- **No envolver expresiones simples en `useMemo`** — el overhead del hook supera el cómputo.
+- **Index maps (`Map`) para lookups repetidos** en vez de `.find()`/`.includes()` en loops → O(1).
+- **`.flatMap()`** en lugar de `.map().filter(Boolean)`; combinar iteraciones múltiples de array en un solo loop.
+- **Hoist de `RegExp`** a nivel módulo (no recrear en cada render).
+- **Early return** cuando el resultado ya está determinado; chequear `length` antes de operaciones caras (sort).
+- **`.toSorted()`** en vez de `.sort()` para inmutabilidad.
+
+## Hydration
+
+- Evitar mismatch sin flicker con scripts inline síncronos cuando se actualiza el DOM antes de hidratar.
+- `suppressHydrationWarning` solo para diferencias server/client intencionales (fechas, IDs).
+- Conditional rendering explícito con ternario, no `&&` (evita renderizar `0` u otros falsy).
+
+## Anti-Patterns
+
+- Componentes definidos dentro del render de otro componente
+- `useMemo`/`useCallback` por default "por las dudas" sin medir
+- `useEffect` para lógica que pertenece a un event handler
+- Guardar en state lo que se puede derivar de props/state existentes
+- `.find()` dentro de `.map()` (O(n²)) sobre listas grandes
+
+---
+
+_Derivado de [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) (react-best-practices, MIT). Condensado al formato Arcane._

package/skills/ai-sdk-setup/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: ai-sdk-setup
+description: "Integrar features de IA en Next.js con el Vercel AI SDK: streaming de chat, tool calling, structured output, agents y RAG. Default a modelos Claude. Usar al agregar chat, generación o agentes a una app Next/Node."
+category: "ai"
+argument-hint: "[chat|stream|tools|structured|agent|rag]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# ai-sdk-setup — Vercel AI SDK con Claude
+
+## MANDATORY WORKFLOW
+
+> **Antes de codear features LLM, leer la skill `claude-api`** para model IDs vigentes, params y pricing. No asumir de memoria.
+
+### Step 0: Gather Requirements
+1. **Caso:** chat / generación one-shot / extracción structured / agente con tools / RAG
+2. **Streaming** al cliente o respuesta completa
+3. **Modelo:** Opus 4.8 (`claude-opus-4-8`, razonamiento) / Sonnet 4.6 (`claude-sonnet-4-6`, balance) / Haiku 4.5 (`claude-haiku-4-5-20251001`, rápido/barato)
+4. ¿Necesita tool calling / structured output / RAG (ver skill `pgvector-search`)?
+
+### Step 1: Instalar
+```bash
+pnpm add ai @ai-sdk/anthropic zod
+# env: ANTHROPIC_API_KEY (validar con Zod en src/lib/env.ts, nunca hardcodear)
+```
+
+### Step 2: Chat con streaming (Route Handler)
+```ts
+// app/api/chat/route.ts
+import { anthropic } from '@ai-sdk/anthropic';
+import { streamText, convertToModelMessages } from 'ai';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const result = streamText({
+    model: anthropic('claude-sonnet-4-6'),
+    messages: convertToModelMessages(messages),
+  });
+  return result.toUIMessageStreamResponse();
+}
+```
+Cliente: `useChat()` de `@ai-sdk/react`.
+
+### Step 3: Structured output (Zod)
+```ts
+const { object } = await generateObject({
+  model: anthropic('claude-sonnet-4-6'),
+  schema: z.object({ sentiment: z.enum(['pos','neg','neutral']), score: z.number() }),
+  prompt: text,
+});
+```
+
+### Step 4: Tool calling / agente
+```ts
+const result = await generateText({
+  model: anthropic('claude-opus-4-8'),
+  tools: {
+    search: tool({
+      description: 'Buscar docs', inputSchema: z.object({ q: z.string() }),
+      execute: async ({ q }) => searchDocs(q),
+    }),
+  },
+  stopWhen: stepCountIs(5),   // loop multi-step controlado
+  prompt,
+});
+```
+
+### Step 5: Buenas prácticas
+- **Server-only** la API key — nunca exponer al cliente
+- Auth en el route handler (como cualquier API route — ver rule `nextjs-code`)
+- Rate limiting en endpoints de IA (costo $)
+- Prompt caching para system prompts grandes (ver skill `claude-api`)
+- Manejar errores de stream y abort (`AbortController`)
+- Validar/parsear toda salida structured con Zod antes de usarla
+
+## Cierre
+
+Probar el endpoint con streaming real, verificar manejo de errores/abort y que la API key nunca llega al cliente. Endpoint funcionando + key server-only → integración **READY**. Confirmar el approach con el usuario antes de escribir código. Siguiente paso: skill `claude-api` para tuning de modelo/caching, o `pgvector-search` para RAG.
+
+---
+
+_Inspirado en las skills de AI SDK de [laguagu/claude-code-nextjs-skills](https://github.com/laguagu/claude-code-nextjs-skills). Adaptado al formato Arcane y a modelos Claude. Verificar API/SDK contra la skill `claude-api`._

package/skills/nestjs-best-practices/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: nestjs-best-practices
+description: "NestJS production best practices: 40 reglas en 10 categorías (arquitectura, DI, errores, seguridad, performance, testing, DB/ORM, API, microservicios, devops) priorizadas por impacto. Usar al escribir/revisar código NestJS."
+category: "backend"
+argument-hint: "[architecture|di|security|performance|testing|database|api|all]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# nestjs-best-practices — Guía priorizada por impacto
+
+40 reglas para aplicaciones NestJS production-ready, organizadas en 10 categorías y priorizadas de **CRITICAL** a **LOW-MEDIUM**. Cada regla del catálogo (en `references/`) trae impacto, ejemplo incorrecto, ejemplo correcto y link a docs.
+
+## MANDATORY WORKFLOW
+
+**No aplicar las 40 reglas a ciegas. Diagnosticar primero, priorizar por impacto.**
+
+### Step 0: Determinar scope
+
+1. **¿Código nuevo o auditoría de existente?** Si es auditoría, leer primero el módulo/servicio objetivo.
+2. **¿Qué categoría aplica?** Mapear el área del problema (ver tabla) o usar `all` para review completa.
+3. **¿Hay síntomas concretos?** (crashes, lentitud, N+1, leaks) → ir directo a la categoría relevante.
+
+### Step 1: Priorizar por impacto
+
+Aplicar en este orden — no bajar de nivel hasta resolver el anterior:
+
+| Prioridad | Categoría | Impacto | Reference |
+|-----------|-----------|---------|-----------|
+| 1 | Architecture | CRITICAL | `references/architecture.md` |
+| 2 | Dependency Injection | CRITICAL | `references/dependency-injection.md` |
+| 3 | Error Handling | HIGH | `references/error-handling.md` |
+| 4 | Security | HIGH | `references/security.md` |
+| 5 | Performance | HIGH | `references/performance.md` |
+| 6 | Database & ORM | MEDIUM-HIGH | `references/database.md` |
+| 7 | Testing | MEDIUM-HIGH | `references/testing.md` |
+| 8 | API Design | MEDIUM | `references/api-design.md` |
+| 9 | Microservices | MEDIUM | `references/microservices-devops.md` |
+| 10 | DevOps & Deployment | LOW-MEDIUM | `references/microservices-devops.md` |
+
+### Step 2: Aplicar + verificar
+
+Para cada regla relevante: leer el ejemplo correcto en el reference, aplicarlo, y verificar contra el checklist de cierre.
+
+### Step 3: Checklist de cierre
+
+- [ ] Sin dependencias circulares (`madge --circular` o equivalente)
+- [ ] Constructor injection en todos los providers; cero `ModuleRef.get()` en runtime
+- [ ] `ValidationPipe` global + DTOs decorados en todos los endpoints
+- [ ] Guards declarativos para auth/authz (no checks manuales)
+- [ ] Sin N+1 (eager loading / joins donde corresponde)
+- [ ] Migraciones versionadas, `synchronize: false` en prod
+- [ ] Graceful shutdown (SIGTERM) + health checks
+- [ ] Structured logging (JSON)
+
+Si todo el checklist pasa → código **COMPLIANT**. Antes de escribir cambios significativos, confirmar el approach con el usuario (Question → Decision → Approval).
+
+## Tabla de mapeo síntoma → categoría
+
+| Síntoma | Categoría |
+|---------|-----------|
+| Crash al arrancar / módulos no resuelven | Architecture, DI |
+| Lentitud en endpoints, muchas queries | Performance, Database |
+| Errores 500 inconsistentes / leaks de stack traces | Error Handling |
+| Endpoints expuestos / brute force / data sensible | Security |
+| Tests frágiles o que llaman servicios reales | Testing |
+| Respuestas inconsistentes / circular refs | API Design |
+
+---
+
+_Adaptado de [kadajett/agent-nestjs-skills](https://github.com/kadajett/agent-nestjs-skills). El repo original compila reglas atómicas (`rules/*.md`) a un `AGENTS.md` vía build script; acá se reorganizó al formato skill+references de Arcane._

package/skills/nestjs-best-practices/references/api-design.md

@@ -0,0 +1,34 @@
+# 8. API Design (MEDIUM)
+
+## 8.1 Use DTOs and Serialization for Responses — MEDIUM
+
+Transformar entidades antes de retornar → controlar exposición, evitar referencias circulares, consistencia.
+```ts
+export class UserResponseDto {
+  @Expose() id: string;
+  @Expose() email: string;
+  @Exclude() password: string; // nunca sale
+}
+// @UseInterceptors(ClassSerializerInterceptor)
+```
+
+## 8.2 Use Interceptors for Cross-Cutting Concerns — MEDIUM
+
+Logging, transformación, formato de respuesta uniforme (`{ data, meta }`) vía interceptors, no repetido en cada handler.
+
+## 8.3 Use Pipes for Input Transformation — MEDIUM
+
+Pipes built-in (`ParseIntPipe`, `ParseUUIDPipe`) y custom para validar/transformar input.
+```ts
+@Get(':id') findOne(@Param('id', ParseUUIDPipe) id: string) {}
+```
+
+## 8.4 Use API Versioning for Breaking Changes — MEDIUM
+
+Versionar endpoints para mantener compatibilidad.
+```ts
+app.enableVersioning({ type: VersioningType.URI }); // /v1/users
+@Controller({ path: 'users', version: '1' })
+```
+
+_Ref: https://docs.nestjs.com/techniques/serialization · https://docs.nestjs.com/techniques/versioning_

package/skills/nestjs-best-practices/references/architecture.md

@@ -0,0 +1,53 @@
+# 1. Architecture (CRITICAL)
+
+## 1.1 Avoid Circular Dependencies — CRITICAL
+
+Causa #1 de crashes en runtime. `forwardRef()` es un parche, no una solución.
+
+**Incorrecto** — A importa B, B importa A:
+```ts
+// users.service.ts → inyecta OrdersService
+// orders.service.ts → inyecta UsersService  ⇒ ciclo
+```
+**Correcto** — extraer lo compartido a un tercer módulo o usar eventos:
+```ts
+// Mover la lógica común a SharedModule, o emitir un evento
+this.eventEmitter.emit('order.created', payload);
+```
+
+## 1.2 Organize by Feature Modules — CRITICAL
+
+Estructurar por feature, no por capa técnica → desarrollo 3-5x más rápido.
+
+```
+src/
+  users/   { users.module.ts, users.controller.ts, users.service.ts, dto/ }
+  orders/  { orders.module.ts, ... }
+```
+No: `controllers/`, `services/`, `repositories/` globales.
+
+## 1.3 Proper Module Sharing — CRITICAL
+
+Exportar servicios desde un módulo dedicado garantiza instancia singleton.
+
+**Correcto:**
+```ts
+@Module({ providers: [UsersService], exports: [UsersService] })
+export class UsersModule {}
+// Otro módulo: imports: [UsersModule] → reusa la MISMA instancia
+```
+Re-declarar el provider en otro módulo crea una instancia nueva → estado inconsistente.
+
+## 1.4 Single Responsibility for Services — CRITICAL
+
+Un servicio = un concepto de dominio. +40% testabilidad. Si un servicio hace auth + email + billing, separarlo.
+
+## 1.5 Event-Driven Architecture for Decoupling — MEDIUM-HIGH
+
+Emitir eventos de dominio (`@nestjs/event-emitter`) para desacoplar módulos y permitir procesamiento async sin dependencias directas.
+
+## 1.6 Repository Pattern for Data Access — HIGH
+
+Encapsular queries en repositorios; separar lógica de negocio de la persistencia. El servicio depende de una abstracción `UserRepository`, no del ORM directamente.
+
+_Ref: https://docs.nestjs.com/modules · https://docs.nestjs.com/fundamentals/circular-dependency_

package/skills/nestjs-best-practices/references/database.md

@@ -0,0 +1,37 @@
+# 7. Database & ORM (MEDIUM-HIGH)
+
+## 7.1 Avoid N+1 Query Problems — HIGH
+
+El asesino silencioso de performance. Eager loading con relations o joins.
+
+**Incorrecto** — 1 query + N queries en loop:
+```ts
+const orders = await this.orderRepo.find();
+for (const o of orders) o.user = await this.userRepo.findOne(o.userId); // N+1
+```
+**Correcto:**
+```ts
+// Prisma
+prisma.order.findMany({ include: { user: true } });
+// TypeORM
+this.orderRepo.find({ relations: ['user'] });
+```
+
+## 7.3 Use Transactions for Multi-Step Operations — MEDIUM-HIGH
+
+Operaciones dependientes en una transacción → consistencia ante fallos.
+```ts
+await this.prisma.$transaction(async (tx) => {
+  await tx.account.update({ where: { id: from }, data: { balance: { decrement: amt } } });
+  await tx.account.update({ where: { id: to },   data: { balance: { increment: amt } } });
+});
+```
+
+## 7.2 Use Database Migrations — MEDIUM-HIGH
+
+Versionar cambios de schema con migraciones. **Nunca `synchronize: true` en producción** (puede borrar datos).
+```ts
+TypeOrmModule.forRoot({ synchronize: false, migrationsRun: true });
+```
+
+_Ref: https://docs.nestjs.com/techniques/database · https://www.prisma.io/docs/orm/prisma-migrate_

package/skills/nestjs-best-practices/references/dependency-injection.md

@@ -0,0 +1,45 @@
+# 2. Dependency Injection (CRITICAL)
+
+## 2.4 Prefer Constructor Injection — CRITICAL
+
+Visibilidad, type safety y testabilidad. Siempre.
+```ts
+@Injectable()
+export class OrdersService {
+  constructor(private readonly users: UsersService) {}
+}
+```
+
+## 2.1 Avoid Service Locator Anti-Pattern — HIGH
+
+**Incorrecto:**
+```ts
+const svc = this.moduleRef.get(UsersService); // dependencia oculta, no testeable
+```
+**Correcto:** inyectar por constructor (2.4). `ModuleRef` solo para casos dinámicos justificados.
+
+## 2.5 Understand Provider Scopes — CRITICAL
+
+`DEFAULT` (singleton) por defecto. `REQUEST` scope tiene costo de performance (instancia por request) → usar solo cuando se necesita contexto de request real.
+```ts
+@Injectable({ scope: Scope.REQUEST }) // solo si es necesario
+```
+
+## 2.6 Use Injection Tokens for Interfaces — HIGH
+
+Las interfaces de TS no existen en runtime → no se pueden inyectar. Usar símbolo o abstract class como token.
+```ts
+export const USER_REPO = Symbol('USER_REPO');
+@Module({ providers: [{ provide: USER_REPO, useClass: PrismaUserRepository }] })
+// constructor(@Inject(USER_REPO) private repo: UserRepository) {}
+```
+
+## 2.2 Interface Segregation — HIGH
+
+Interfaces chicas y enfocadas, no "fat interfaces" que fuerzan dependencias sin usar.
+
+## 2.3 Liskov Substitution — HIGH
+
+Toda implementación de una interfaz honra el contrato idéntico → intercambiables sin romper consumidores.
+
+_Ref: https://docs.nestjs.com/fundamentals/custom-providers · https://docs.nestjs.com/fundamentals/injection-scopes_

package/skills/nestjs-best-practices/references/error-handling.md

@@ -0,0 +1,43 @@
+# 3. Error Handling (HIGH)
+
+## 3.2 Throw HTTP Exceptions from Services — HIGH
+
+Los servicios lanzan excepciones, no retornan objetos de error.
+
+**Incorrecto:**
+```ts
+return { error: 'not found' }; // el controller tiene que adivinar
+```
+**Correcto:**
+```ts
+throw new NotFoundException(`User ${id} not found`);
+```
+
+## 3.1 Handle Async Errors Properly — HIGH
+
+Fire-and-forget y background tasks deben atrapar errores → si no, unhandled rejection puede tumbar el proceso.
+
+**Incorrecto:**
+```ts
+this.mailer.send(email); // floating promise, error perdido
+```
+**Correcto:**
+```ts
+void this.mailer.send(email).catch(err => this.logger.error('mail failed', err));
+```
+
+## 3.3 Use Exception Filters — HIGH
+
+Filtro global para formato de respuesta de error consistente y centralizado.
+```ts
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    // shape único: { statusCode, message, timestamp, path }
+  }
+}
+// app.useGlobalFilters(new AllExceptionsFilter());
+```
+Nunca filtrar stack traces crudos al cliente en producción.
+
+_Ref: https://docs.nestjs.com/exception-filters_

package/skills/nestjs-best-practices/references/microservices-devops.md

@@ -0,0 +1,41 @@
+# 9. Microservices (MEDIUM) & 10. DevOps (LOW-MEDIUM)
+
+## 9.1 Implement Health Checks — MEDIUM
+
+Endpoints readiness/liveness con `@nestjs/terminus` para que el orquestador maneje la salud del servicio.
+```ts
+@Get('health') @HealthCheck()
+check() { return this.health.check([() => this.db.pingCheck('db')]); }
+```
+
+## 9.2 Message and Event Patterns Correctly — MEDIUM
+
+Distinguir request-response (`@MessagePattern`) de event-based (`@EventPattern`). Usar el patrón correcto según si se espera respuesta.
+
+## 9.3 Use Message Queues for Background Jobs — MEDIUM
+
+Offload de tareas largas a colas (`@nestjs/bull` / BullMQ) → no bloquear handlers de request.
+```ts
+await this.reportQueue.add('generate', { userId }); // responde rápido, procesa async
+```
+
+## 10.1 Implement Graceful Shutdown — MEDIUM
+
+Escuchar SIGTERM, completar requests in-flight antes de salir.
+```ts
+app.enableShutdownHooks();
+// onModuleDestroy() { await this.drainConnections(); }
+```
+
+## 10.2 Use ConfigModule for Environment Config — MEDIUM
+
+Config por entorno vía `ConfigModule`, validada al boot. Nada hardcodeado.
+```ts
+ConfigModule.forRoot({ validationSchema: Joi.object({ DATABASE_URL: Joi.string().required() }) });
+```
+
+## 10.3 Use Structured Logging — LOW-MEDIUM
+
+Logging JSON consistente (pino/winston) con `request_id`, `trace_id` para parseo/filtrado en producción.
+
+_Ref: https://docs.nestjs.com/recipes/terminus · https://docs.nestjs.com/microservices/basics · https://docs.nestjs.com/techniques/configuration_

package/skills/nestjs-best-practices/references/performance.md

@@ -0,0 +1,32 @@
+# 5. Performance (HIGH)
+
+## 5.3 Optimize Database Queries — HIGH
+
+Seleccionar solo columnas necesarias, índices apropiados, no over-fetch de relaciones.
+```ts
+// Prisma: select explícito en vez de traer la fila entera + relaciones
+prisma.user.findMany({ select: { id: true, email: true } });
+```
+
+## 5.4 Use Caching Strategically — HIGH
+
+Cachear operaciones caras con TTL apropiado e invalidación basada en eventos.
+```ts
+@UseInterceptors(CacheInterceptor)
+@CacheTTL(30)
+@Get('stats') getStats() { /* ... */ }
+```
+
+## 5.1 Async Lifecycle Hooks Correctly — HIGH
+
+Retornar promesas de hooks async; constructores síncronos (no bloquear el arranque).
+```ts
+async onModuleInit() { await this.warmupCache(); } // ✓
+// constructor(){ await ... }  ✗ no se puede / bloquea
+```
+
+## 5.2 Lazy Loading for Large Modules — MEDIUM
+
+Diferir inicialización de módulos poco usados con `LazyModuleLoader` → menor tiempo de arranque y memoria.
+
+_Ref: https://docs.nestjs.com/techniques/caching · https://docs.nestjs.com/fundamentals/lazy-loading-modules_

package/skills/nestjs-best-practices/references/security.md

@@ -0,0 +1,50 @@
+# 4. Security (HIGH)
+
+## 4.1 Secure JWT Authentication — CRITICAL
+
+Tokens de vida corta (15m) + refresh tokens. Secreto en env/secret manager. Nunca data sensible en el payload.
+```ts
+JwtModule.register({
+  secret: process.env.JWT_SECRET,        // nunca hardcodeado
+  signOptions: { expiresIn: '15m' },
+});
+// payload: { sub: userId, role }  ← nada de passwords, emails completos, PII
+```
+
+## 4.5 Validate All Input with DTOs and Pipes — HIGH
+
+`ValidationPipe` global + DTOs decorados. Rechazar input malformado antes de procesarlo.
+```ts
+app.useGlobalPipes(new ValidationPipe({
+  whitelist: true,            // descarta props no declaradas
+  forbidNonWhitelisted: true, // 400 si vienen props extra
+  transform: true,
+}));
+
+export class CreateUserDto {
+  @IsEmail() email: string;
+  @MinLength(8) password: string;
+}
+```
+
+## 4.4 Use Guards for AuthN/AuthZ — HIGH
+
+Guards declarativos, no checks manuales en cada handler.
+```ts
+@UseGuards(JwtAuthGuard, RolesGuard)
+@Roles('admin')
+@Get('users') findAll() { /* ... */ }
+```
+
+## 4.2 Rate Limiting — HIGH
+
+`@nestjs/throttler`, límites por endpoint (login más estricto que lecturas).
+```ts
+@Throttle({ default: { limit: 5, ttl: 60000 } }) // 5/min en /login
+```
+
+## 4.3 Sanitize Output to Prevent XSS — HIGH
+
+Sanitizar contenido generado por usuario antes de almacenar; `Content-Type` correcto en respuestas.
+
+_Ref: https://docs.nestjs.com/security/authentication · https://docs.nestjs.com/security/rate-limiting_

package/skills/nestjs-best-practices/references/testing.md

@@ -0,0 +1,32 @@
+# 6. Testing (MEDIUM-HIGH)
+
+## 6.3 Use Testing Module for Unit Tests — HIGH
+
+Entorno aislado con `Test.createTestingModule` y dependencias mockeadas.
+```ts
+const moduleRef = await Test.createTestingModule({
+  providers: [
+    OrdersService,
+    { provide: UserRepository, useValue: mockUserRepo },
+  ],
+}).compile();
+const service = moduleRef.get(OrdersService);
+```
+
+## 6.2 Mock External Services in Tests — HIGH
+
+Nunca llamar APIs o DBs reales en tests. Mockear todas las dependencias externas con escenarios realistas (éxito, error, timeout).
+
+## 6.1 Use Supertest for E2E Testing — HIGH
+
+Probar el ciclo completo request/response incluyendo middleware, guards y pipes. Setup/teardown apropiados.
+```ts
+const app = moduleRef.createNestApplication();
+await app.init();
+await request(app.getHttpServer())
+  .post('/users').send({ email: 'a@b.com', password: 'secret123' })
+  .expect(201);
+await app.close();
+```
+
+_Ref: https://docs.nestjs.com/fundamentals/testing_

package/skills/nestjs-scaffold/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: nestjs-scaffold
+description: "Scaffold de API NestJS production-ready con módulos por feature, DI, ValidationPipe global, Prisma/Drizzle, guards de auth y testing. Usar para iniciar un backend NestJS nuevo."
+category: "backend"
+argument-hint: "[project-name]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# nestjs-scaffold — NestJS API Scaffolder
+
+## MANDATORY WORKFLOW
+
+**Antes de generar cualquier código, completar estos pasos en orden.**
+
+### Step 0: Gather Requirements
+1. **Nombre del servicio** (kebab-case)
+2. **Transport:** REST (default) / GraphQL / microservicio
+3. **ORM:** Prisma (default) / Drizzle / TypeORM
+4. **DB:** PostgreSQL (default) / MySQL
+5. **Auth:** JWT + refresh (default) / OAuth / ninguna
+6. **Deploy:** Docker (default) / Railway / AWS ECS
+
+### Step 1: Crear base
+```bash
+npm i -g @nestjs/cli
+nest new <name> --package-manager pnpm
+cd <name>
+nest g module users && nest g controller users && nest g service users
+```
+
+### Step 2: Estructura (feature modules — NO por capa)
+```
+src/
+  users/   { users.module.ts, users.controller.ts, users.service.ts, dto/, entities/ }
+  auth/    { auth.module.ts, jwt.strategy.ts, guards/, decorators/ }
+  common/  { filters/, interceptors/, pipes/ }
+  config/  { config.module.ts, env.validation.ts }
+  main.ts
+```
+
+### Step 3: Bootstrap no negociable (`main.ts`)
+```ts
+app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }));
+app.useGlobalFilters(new AllExceptionsFilter());
+app.enableShutdownHooks();           // graceful shutdown
+app.enableVersioning({ type: VersioningType.URI });
+```
+
+### Step 4: Defaults
+- Constructor injection siempre; cero `ModuleRef.get()` en runtime
+- DTOs decorados (`class-validator`) en todos los endpoints
+- Guards declarativos para auth/authz
+- `ConfigModule` con validación de env (Joi/Zod) al boot
+- Migraciones versionadas, `synchronize: false`
+- Health check (`@nestjs/terminus`) + structured logging (pino)
+- Tests: `Test.createTestingModule` (unit) + supertest (e2e)
+
+### Step 5: Verificar
+`npm run build` + `npm run test`. Revisar contra la rule `nestjs-code` y el skill `nestjs-best-practices`. Build + tests verdes → scaffold **READY**.
+
+## Stack Defaults
+
+| Componente | Default |
+|------------|---------|
+| Framework | NestJS 10+ |
+| ORM | Prisma |
+| DB | PostgreSQL |
+| Auth | JWT + refresh tokens |
+| Validación | class-validator + ValidationPipe |
+| Testing | Jest + supertest |
+| Deploy | Docker |
+
+---
+
+_Inspirado en las skills NestJS de [kadajett/agent-nestjs-skills](https://github.com/kadajett/agent-nestjs-skills) y [giuseppe-trisciuoglio/developer-kit](https://github.com/giuseppe-trisciuoglio/developer-kit). Adaptado al formato Arcane._