rsc-universal 0.1.1

package/skills/neon/references/branching-ci.md

@@ -0,0 +1,86 @@
+# Per-PR Neon branching in CI
+
+Replicate the Neon + Vercel preview integration anywhere: create an isolated, full-data branch when a
+PR opens, migrate and seed it, hand the pooled connection string to the preview app, and delete the
+branch when the PR closes. A branch is copy-on-write (instant, no data copied) and scales to zero, so
+even a dozen open PRs cost almost nothing.
+
+## `neonctl` command reference
+
+`neonctl` (alias `neon`) is the official CLI. Authenticate in CI with `NEON_API_KEY`.
+
+| Command | Purpose |
+| --- | --- |
+| `neonctl branches create --name <n> --parent main` | Fork a new branch from production at the current point in time. |
+| `neonctl connection-string <branch> --pooled` | Print the **pooled** (`-pooler`) string for the app runtime. |
+| `neonctl connection-string <branch>` | Print the **direct** string for migrations/DDL. |
+| `neonctl branches list` | List branches (find a stale one to delete). |
+| `neonctl branches delete <branch>` | Tear the branch down on PR close. |
+
+## GitHub Actions: create on open, delete on close
+
+```yaml
+name: neon-pr-branch
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, closed]
+
+env:
+  NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
+  NEON_PROJECT_ID: ${{ vars.NEON_PROJECT_ID }}
+
+jobs:
+  create_and_migrate:
+    if: github.event.action != 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npm i -g neonctl
+      - name: Create branch
+        run: neonctl branches create --name pr-${{ github.event.number }} --parent main --project-id "$NEON_PROJECT_ID"
+      - name: Resolve strings
+        id: db
+        run: |
+          DIRECT=$(neonctl connection-string pr-${{ github.event.number }} --project-id "$NEON_PROJECT_ID")
+          POOLED=$(neonctl connection-string pr-${{ github.event.number }} --pooled --project-id "$NEON_PROJECT_ID")
+          echo "::add-mask::$DIRECT"; echo "::add-mask::$POOLED"
+          echo "direct=$DIRECT" >> "$GITHUB_OUTPUT"
+          echo "pooled=$POOLED" >> "$GITHUB_OUTPUT"
+      - name: Migrate + seed (DIRECT string — DDL needs a real session)
+        env:
+          DATABASE_URL: ${{ steps.db.outputs.direct }}
+        run: |
+          npm ci
+          npm run db:migrate
+          npm run db:seed
+      # Hand steps.db.outputs.pooled to the preview deploy as the app DATABASE_URL.
+
+  delete:
+    if: github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - run: npm i -g neonctl
+      - run: neonctl branches delete pr-${{ github.event.number }} --project-id "$NEON_PROJECT_ID"
+```
+
+Rules that keep this honest:
+
+- Migrations and seed run against the **direct** string — PgBouncer transaction-pooling breaks DDL and advisory locks.
+- The preview app gets the **pooled** (`-pooler`) string — serverless concurrency needs the pool.
+- The `closed` event covers both merge and abandon, so branches never accumulate.
+
+## Neon API (if you can't use the CLI)
+
+Same flow over REST with a bearer `NEON_API_KEY`:
+
+| Step | Endpoint |
+| --- | --- |
+| Create branch | `POST /api/v2/projects/{project_id}/branches` |
+| Get branch endpoints / connection URI | `GET /api/v2/projects/{project_id}/branches/{branch_id}/endpoints` |
+| Delete branch | `DELETE /api/v2/projects/{project_id}/branches/{branch_id}` |
+
+Pass `endpoints[].pooler_enabled` / request the pooled URI for the app, the plain URI for migrations.
+Engine-level migration mechanics (expand-contract, `CONCURRENTLY`, batched backfill) are not Neon's —
+see `../../postgresdb/SKILL.md`.

package/skills/neon/scripts/verify.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# verify.sh — static Neon foot-gun scan. Read-only, no network, no DB.
+# Usage: verify.sh [TARGET_DIR]   (defaults to current directory)
+# Exit 0 when clean or no Neon usage found; non-zero only on a hard FAIL.
+set -uo pipefail
+
+TARGET="${1:-.}"
+fails=0
+
+say()  { printf '%s\n' "$*"; }
+pass() { say "PASS: $*"; }
+warn() { say "WARN: $*"; }
+fail() { say "FAIL: $*"; fails=$((fails+1)); }
+
+# Files that actually reference Neon — keeps the scan scoped and avoids false hits.
+# Portable across bash 3.2 (macOS) and 4+: newline-separated, then filter by grep.
+neon_files=()
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  if grep -qE '@neondatabase/serverless|neon\.tech' "$f" 2>/dev/null; then
+    neon_files+=("$f")
+  fi
+done < <(
+  find "$TARGET" \
+    -type d \( -name node_modules -o -name .git -o -name dist -o -name build -o -name .next \) -prune -o \
+    -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.mjs' -o -name '*.env' -o -name '.env*' \) -print 2>/dev/null
+)
+
+if [ "${#neon_files[@]}" -eq 0 ]; then
+  say "no Neon usage found — nothing to check"
+  exit 0
+fi
+
+# (a) WebSocket Pool/Client created at module/top scope (heuristic: `new Pool(`/`new Client(`
+#     on a line with no leading indentation, i.e. not inside a function/handler block).
+for f in "${neon_files[@]}"; do
+  if grep -nE '^(export +)?(const|let|var) +[A-Za-z0-9_]+ *= *new +(Pool|Client) *\(' "$f" >/dev/null 2>&1; then
+    while IFS= read -r line; do
+      fail "module-scope WebSocket Pool/Client in $f -> $line (move inside the request handler; it leaks connections)"
+    done < <(grep -nE '^(export +)?(const|let|var) +[A-Za-z0-9_]+ *= *new +(Pool|Client) *\(' "$f")
+  fi
+done
+
+# (b) pooled string in a migration config, or a non-pooler Neon host used as the app DATABASE_URL.
+for f in "${neon_files[@]}"; do
+  base="$(basename "$f")"
+  case "$base" in
+    *migrat*|drizzle.config.*|knexfile.*|*.env.migrat*)
+      if grep -nE '-pooler\.[^ "'\'']*neon\.tech' "$f" >/dev/null 2>&1; then
+        warn "pooled (-pooler) host in migration config $f (migrations/DDL need the DIRECT string)"
+      fi
+      ;;
+  esac
+  # App DATABASE_URL pointing at a non-pooler Neon host.
+  if grep -nE 'DATABASE_URL *= *.*[^-]neon\.tech' "$f" 2>/dev/null | grep -vqE '\-pooler\.' ; then
+    if grep -nE 'DATABASE_URL *= *.*[a-z0-9-]+\.[a-z0-9-]*\.?neon\.tech' "$f" 2>/dev/null | grep -vqE '\-pooler' ; then
+      warn "DATABASE_URL uses a non -pooler Neon host in $f (app runtime should use the POOLED string)"
+    fi
+  fi
+done
+
+# (c) `ws` imported but neonConfig.webSocketConstructor never assigned (Node <=21 will fail silently).
+for f in "${neon_files[@]}"; do
+  if grep -qE "(import +ws +from +['\"]ws['\"]|require\(['\"]ws['\"]\))" "$f" 2>/dev/null; then
+    if ! grep -qE 'neonConfig\.webSocketConstructor *=' "$f" 2>/dev/null; then
+      warn "ws imported without neonConfig.webSocketConstructor in $f (required on Node <=21)"
+    fi
+  fi
+done
+
+if [ "$fails" -gt 0 ]; then
+  say "---"
+  say "$fails hard failure(s)."
+  exit 1
+fi
+say "---"
+say "no hard failures."
+exit 0

package/skills/nestjs/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: nestjs
+description: "Use when building or structuring a NestJS backend — feature modules, providers, controllers, DI wiring, and the cross-cutting layer (guards, interceptors, pipes, exception filters) — including binding-scope and request-lifecycle decisions and Nest-specific testing. Triggers: 'create a NestJS module', 'wire a custom provider with useFactory', 'APP_GUARD vs @UseGuards on the controller', 'my request-scoped provider is undefined in a guard', 'A circular dependency has been detected at bootstrap', 'mock a repository provider with overrideProvider', 'monta un módulo de Nest', 'guard de autenticación JWT en NestJS'. NOT a bare Express/Node service with no DI (that is nodejs)."
+tags: [nestjs, nodejs, backend, dependency-injection, guards, pipes, testing, typescript]
+recommends: [nodejs, typescript, api-design, prisma-orm, testing-web]
+origin: risco
+---
+
+# NestJS
+
+Build server-side Node apps the way NestJS intends: feature modules, providers wired through the DI container, controllers, and a cross-cutting layer bound at a deliberate scope. This skill is about Nest-specific mechanics — how DI scopes resolve, what order the request lifecycle runs in, where to bind guards/pipes/interceptors/filters, and how to test it with `Test.createTestingModule`.
+
+## Use this when
+
+- Scaffolding or extending a Nest app: new module, controller, provider, resolver.
+- Wiring DI: `useClass` / `useValue` / `useFactory` / `useExisting`, injection tokens, `forwardRef`, dynamic modules (`forRoot` / `forRootAsync`).
+- Adding cross-cutting behavior and deciding global vs controller vs route binding.
+- "Why is my request-scoped provider undefined" / "circular dependency detected at bootstrap".
+- Unit tests with mock providers and e2e tests with Supertest against the real Nest app.
+
+## Not this when
+
+- Bare Express/Fastify/`http` service, no `@Module`/`@Injectable` → `../nodejs/SKILL.md`. Nest starts the moment the DI container appears.
+- REST resource modeling, versioning, status codes, idempotency (framework-agnostic) → `../api-design/SKILL.md`. Nest is where you *implement* those decisions.
+- Designing the schema / writing queries / migrations → `../prisma-orm/SKILL.md`. *Injecting* a repo or `DataSource` provider stays here; designing the table does not.
+- Generic JS/TS test infra (Jest config, coverage thresholds, monorepo) → `../testing-web/SKILL.md`. The Nest harness (`TestingModule`, `overrideProvider`, Supertest bootstrap) stays here.
+
+## Mental model
+
+Everything is a **provider** in a directed DI graph. **Modules** draw the boundaries of that graph — a provider is only reachable where it is provided or imported. **Cross-cutting concerns** (guards, interceptors, pipes, filters) are decorators bound at a scope you choose: global, controller, or route. Get those three right and the rest is plumbing.
+
+The request lifecycle runs in a fixed order. Memorize it — most "my guard can't see the validated body" bugs are an ordering misunderstanding:
+
+```text
+req → middleware → guards → interceptors(pre) → pipes → handler → interceptors(post) → exception filters → res
+```
+
+So pipes run *after* guards (a guard cannot read a transformed DTO), and filters catch everything thrown downstream. Source: NestJS request-lifecycle docs.
+
+## Module design
+
+One feature module per bounded context. Rules, each with its why:
+
+- **`exports` is the module's public API.** A provider not exported is private to that module — that is the encapsulation, lean on it.
+- **`imports` brings in another module's exports; it does not re-declare providers.** Re-declaring a provider in two modules gives you two singletons and silent state bugs.
+- **Keep `AppModule` thin.** It wires feature modules and global config, nothing else. A god `AppModule` that declares every controller becomes an untestable circular-dependency magnet.
+- **Use a dynamic module (`forRoot` / `forRootAsync`) for configurable infrastructure** (DB, cache, mailer) so consumers pass options instead of editing the module.
+
+```typescript
+// Bad — everything dumped in AppModule, no boundaries
+@Module({ controllers: [OrdersController, UsersController, BillingController],
+          providers: [OrdersService, UsersService, BillingService, PrismaService] })
+export class AppModule {}
+
+// Good — a feature module owns its slice and exports only its public surface
+@Module({
+  imports: [PrismaModule],
+  controllers: [OrdersController],
+  providers: [OrdersService],
+  exports: [OrdersService], // other modules consume the service, not the repo
+})
+export class OrdersModule {}
+```
+
+## Providers & DI
+
+Pick the custom-provider form by intent:
+
+| Form | Use it when | Resolved by |
+|------|-------------|-------------|
+| `useClass` | Default — swap implementation by class (e.g. real vs fake mailer) | Nest instantiates |
+| `useValue` | A ready object/constant: config, a mock in tests | Used as-is |
+| `useFactory` | Value needs computing or other providers (`inject: [...]`) | Your factory fn |
+| `useExisting` | Alias an existing token to a new token | Reuses instance |
+
+A non-class token needs explicit injection — Nest has no type to reflect on:
+
+```typescript
+const STRIPE = 'STRIPE_CLIENT';
+
+@Module({
+  providers: [{
+    provide: STRIPE,
+    useFactory: (cfg: ConfigService) => new Stripe(cfg.get('STRIPE_KEY')),
+    inject: [ConfigService],
+  }],
+  exports: [STRIPE],
+})
+export class PaymentsModule {}
+
+@Injectable()
+export class CheckoutService {
+  constructor(@Inject(STRIPE) private readonly stripe: Stripe) {}
+}
+```
+
+`forwardRef(() => X)` is a last resort, not a fix — it works around a circular dependency that usually signals two modules that should share a third. Reach for the refactor first; if you must, `forwardRef` goes on *both* sides. See the anti-patterns table.
+
+## Provider scopes
+
+| Scope | Lifetime | Use when |
+|-------|----------|----------|
+| `DEFAULT` | Singleton (one per app) | Almost always — stateless services |
+| `REQUEST` | New instance per request | You genuinely need per-request state (`@Inject(REQUEST)` for the live request) |
+| `TRANSIENT` | New instance per consumer | Each injector gets its own copy |
+
+REQUEST scope **bubbles up**: any provider that injects a request-scoped provider becomes request-scoped too, and so does the controller — with a real per-request instantiation cost. Default to singleton; reach for REQUEST only when you must.
+
+```typescript
+@Injectable({ scope: Scope.REQUEST })
+export class RequestContext {
+  constructor(@Inject(REQUEST) private readonly req: Request) {}
+  get userId() { return this.req.user?.id; }
+}
+```
+
+The classic gotcha: a request-scoped provider injected into a **guard** reads as undefined or stale because guards run early and the scope propagation is not what you assumed. If a guard needs request data, pull it from `ExecutionContext` (`context.switchToHttp().getRequest()`), not from an injected request-scoped service.
+
+## Cross-cutting layer
+
+Pick the primitive by what it is *for*:
+
+| Primitive | Job | Signature |
+|-----------|-----|-----------|
+| Guard | Authorize — allow/deny the request | returns `boolean` / `Promise<boolean>` |
+| Interceptor | Wrap the handler before **and** after (logging, transform, timeout, cache) | RxJS, `handle().pipe(...)` |
+| Pipe | Validate and/or transform an input argument | returns transformed value or throws |
+| Exception filter | Catch a thrown error and shape the response | `catch(exception, host)` |
+
+Then pick the binding scope:
+
+| Binding | Reach | Can inject deps? |
+|---------|-------|------------------|
+| `APP_GUARD` / `APP_PIPE` / `APP_INTERCEPTOR` / `APP_FILTER` token in a module's `providers` | Global | **Yes** — resolved by the DI container |
+| `@UseGuards(X)` / `@UsePipes(X)` on controller or route | Local | Yes if you pass the class |
+| `app.useGlobalGuards(new X())` in `main.ts` | Global | **No** — you instantiated it yourself |
+
+The gotcha that bites everyone: `app.useGlobalPipes(new ValidationPipe())` works, but a guard or pipe that needs to inject a `ConfigService` **cannot** be registered with `new` — Nest never resolved it. Use the `APP_*` token instead so the container builds it:
+
+```typescript
+// Good — global AND DI-capable
+@Module({
+  providers: [{ provide: APP_GUARD, useClass: AuthGuard }],
+})
+export class AppModule {}
+```
+
+Deeper material — `ExecutionContext`, custom param decorators, `Reflector` + `SetMetadata` for role/`@Public()` guards, transform/timeout interceptors, filter shape, multiple-binding order — is in `references/cross-cutting.md`.
+
+## Validation
+
+DTO + `ValidationPipe` + `class-validator`/`class-transformer`. The production-safe config:
+
+```typescript
+// main.ts
+app.useGlobalPipes(new ValidationPipe({
+  whitelist: true,            // strip properties with no decorator
+  forbidNonWhitelisted: true, // 400 on unknown properties instead of silently dropping
+  transform: true,            // coerce payloads to DTO class instances (and primitives)
+}));
+```
+
+```typescript
+export class CreateOrderDto {
+  @IsString() @IsNotEmpty()
+  sku: string;
+
+  @IsInt() @Min(1)
+  quantity: number;
+}
+```
+
+If the pipe needs to inject something, bind it globally via `APP_PIPE` instead of `new` (same DI rule as above).
+
+## Testing
+
+`Test.createTestingModule({...}).compile()` returns a `TestingModule` you pull providers from. Decision line: **unit-test a provider with its collaborators mocked; e2e-test the wired app over HTTP.**
+
+Unit — mock the collaborators:
+
+```typescript
+const moduleRef = await Test.createTestingModule({
+  providers: [OrdersService],
+})
+  .overrideProvider(OrderRepository)
+  .useValue({ findById: vi.fn().mockResolvedValue(order) })
+  .compile();
+
+const service = moduleRef.get(OrdersService);
+```
+
+e2e — boot the real app and hit it with Supertest. **Replicate the global config from `main.ts`** (pipes, filters, guards) or the test passes while prod 400s:
+
+```typescript
+const app = moduleRef.createNestApplication();
+app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true })); // mirror main.ts
+await app.init();
+await request(app.getHttpServer()).post('/orders').send(body).expect(201);
+```
+
+`overrideGuard(AuthGuard).useValue({ canActivate: () => true })` lets an e2e test bypass auth. Full recipes — mocking a repo, request-scoped via `resolve()`, ConfigModule in tests, Vitest vs Jest — in `references/testing-recipes.md`.
+
+## Bootstrap & tooling
+
+- Scaffold with the CLI, not by hand: `nest g resource orders`, `nest g module orders`, `nest g service orders`. It wires the module registration for you.
+- **NestJS 11** is current (Jan 2025), requires **Node.js 20+**, and ships **Express v5** as the default HTTP adapter (Fastify remains an option).
+- Use the **SWC builder** for dev — roughly 20x faster builds and faster cold start than `tsc`. Keep `tsc` for type-checking in CI.
+- ESM is first-class in v11 (top-level await aligned with modern Node).
+- The official harness is moving toward **Vitest** (SWC-powered) alongside Jest; Jest is still fully supported and is what `nest new` historically scaffolds.
+
+## Anti-patterns
+
+| Anti-pattern | Why it hurts | Do instead |
+|--------------|--------------|------------|
+| God `AppModule` declaring every controller/provider | No boundaries; breeds circular deps; untestable | One feature module per bounded context, `exports` = public API |
+| `new OrdersService(repo)` inside a controller/service | Bypasses DI; same class becomes two unmocked instances | Constructor-inject; let the container build it |
+| Business logic in the controller | Controllers should map HTTP ↔ service calls only | Push logic into a provider; controller stays thin |
+| `Scope.REQUEST` by default | Bubbles up the chain, per-request cost, surprise undefined in guards | Default singleton; REQUEST only with a real reason |
+| `useGlobalPipes(new X())` for a pipe that needs deps | `new` is not DI-resolved; injected deps are undefined | Bind via `APP_PIPE` / `APP_GUARD` token in `providers` |
+| e2e test that skips `main.ts` globals | Green test, red prod — validation/filters not applied | Replicate global pipes/filters/guards in the e2e bootstrap |
+| `forwardRef` sprinkled to silence "circular dependency" | Hides the real coupling; fragile bootstrap order | Refactor to a shared module; `forwardRef` only as last resort, on both sides |
+
+## Verify
+
+Run `scripts/verify.sh [dir]` to statically catch DI bypasses without a Nest install. It hard-fails only on `new XxxService(...)` outside test files; everything else is a warning. Exits 0 on a clean or empty target.

package/skills/nestjs/evals/README.md

@@ -0,0 +1,3 @@
+# nestjs evals
+
+Trigger and capability checks for NestJS backend work.

package/skills/nestjs/evals/cases.yaml

@@ -0,0 +1,38 @@
+skill: nestjs
+
+should_trigger:
+  - prompt: "Create a NestJS module with a controller, provider and repository provider."
+    why: "Feature modules/controllers/providers are core NestJS mechanics."
+  - prompt: "Should this auth guard be APP_GUARD or @UseGuards on the controller?"
+    why: "Guard binding scope is a Nest-specific cross-cutting decision."
+  - prompt: "My request-scoped provider is undefined inside a Nest guard."
+    why: "DI scope and lifecycle issues belong to NestJS."
+  - prompt: "Mock a repository provider with overrideProvider in a Nest test."
+    why: "TestingModule and overrideProvider are Nest-specific testing APIs."
+  - prompt: "Monta un modulo de Nest con JWT guard y pipes de validacion."
+    why: "Spanish Nest module plus guards/pipes triggers this skill."
+
+should_not_trigger:
+  - prompt: "Build a bare Express route with no DI container."
+    route_to: "nodejs"
+    why: "Bare Express without Nest modules/providers is Node.js, not NestJS."
+  - prompt: "Design REST status codes and idempotency for this API."
+    route_to: "api-design"
+    why: "Framework-agnostic API design belongs elsewhere."
+  - prompt: "Design the Postgres schema for orders."
+    route_to: "postgresdb"
+    why: "Database schema design is not a Nest DI/module concern."
+  - prompt: "Fix a generic TypeScript conditional type."
+    route_to: "typescript"
+    why: "Pure TypeScript typing belongs to the TypeScript skill."
+
+capability:
+  - scenario: "A user asks to add a NestJS Orders module with a service, controller, injected repository, validation pipe and tests."
+    must_include:
+      - "Defines a feature module boundary and keeps AppModule thin."
+      - "Wires providers through Nest DI rather than manually new-ing dependencies."
+      - "Chooses provider form (useClass/useValue/useFactory/useExisting) by intent."
+      - "Places guards/pipes/interceptors at the right scope and respects request lifecycle order."
+      - "Uses Test.createTestingModule and overrideProvider for unit tests."
+      - "Routes schema/query design to database skills when needed."
+      - "Avoids circular dependencies or uses forwardRef only as a last resort."

package/skills/nestjs/references/cross-cutting.md

@@ -0,0 +1,135 @@
+# Cross-cutting layer: deep treatment
+
+Guards, interceptors, pipes, and filters share one base idea — they read the `ExecutionContext` and run at a fixed point in the request lifecycle — but each has a distinct job. This is the depth the SKILL body points to.
+
+## ExecutionContext
+
+Every cross-cutting primitive receives an `ExecutionContext` (a superset of `ArgumentsHost`). It abstracts the transport so the same guard works over HTTP, WebSockets, or microservices.
+
+```typescript
+@Injectable()
+export class AuthGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const req = context.switchToHttp().getRequest<Request>();
+    return Boolean(req.headers.authorization);
+  }
+}
+```
+
+Pull request data from the context here, not from an injected request-scoped provider — guards run before the scope you expect is settled.
+
+## Custom param decorators
+
+Extract repeated `req.user` plumbing into a decorator built on `createParamDecorator`:
+
+```typescript
+export const CurrentUser = createParamDecorator(
+  (_data: unknown, ctx: ExecutionContext) => {
+    return ctx.switchToHttp().getRequest().user;
+  },
+);
+
+// handler
+@Get('me')
+me(@CurrentUser() user: User) { return user; }
+```
+
+## Reflector + SetMetadata: role and @Public() guards
+
+Attach metadata at the route/controller with a decorator, read it in the guard with `Reflector`. This is how you build role checks and a `@Public()` opt-out for a global guard.
+
+```typescript
+export const IS_PUBLIC = 'isPublic';
+export const Public = () => SetMetadata(IS_PUBLIC, true);
+
+export const ROLES = 'roles';
+export const Roles = (...roles: string[]) => SetMetadata(ROLES, roles);
+```
+
+```typescript
+@Injectable()
+export class AuthGuard implements CanActivate {
+  constructor(private readonly reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    if (isPublic) return true;
+
+    const required = this.reflector.getAllAndOverride<string[]>(ROLES, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    const req = context.switchToHttp().getRequest();
+    if (!required?.length) return Boolean(req.user);
+    return required.some((r) => req.user?.roles?.includes(r));
+  }
+}
+```
+
+`getAllAndOverride` merges handler-level over class-level metadata — route decorator wins over controller decorator. Bind this guard globally and DI-capable via `APP_GUARD` so `Reflector` is injected:
+
+```typescript
+@Module({ providers: [{ provide: APP_GUARD, useClass: AuthGuard }] })
+export class AppModule {}
+```
+
+## Interceptors (RxJS)
+
+Interceptors wrap the handler. The pre-handler code runs before `next.handle()`; the operators you pipe onto the returned stream run after. They are RxJS observables — use `map`, `tap`, `timeout`, `catchError`.
+
+Response transform:
+
+```typescript
+@Injectable()
+export class WrapResponseInterceptor implements NestInterceptor {
+  intercept(_ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
+    return next.handle().pipe(map((data) => ({ data, ts: Date.now() })));
+  }
+}
+```
+
+Timeout:
+
+```typescript
+@Injectable()
+export class TimeoutInterceptor implements NestInterceptor {
+  intercept(_ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
+    return next.handle().pipe(
+      timeout(5000),
+      catchError((err) =>
+        err instanceof TimeoutError
+          ? throwError(() => new RequestTimeoutException())
+          : throwError(() => err),
+      ),
+    );
+  }
+}
+```
+
+## Exception filters
+
+A filter catches thrown errors and shapes the response. Declare what it catches with `@Catch(...)`; an empty `@Catch()` catches everything.
+
+```typescript
+@Catch(HttpException)
+export class HttpExceptionFilter implements ExceptionFilter {
+  catch(exception: HttpException, host: ArgumentsHost) {
+    const res = host.switchToHttp().getResponse<Response>();
+    const status = exception.getStatus();
+    res.status(status).json({
+      statusCode: status,
+      message: exception.message,
+      timestamp: new Date().toISOString(),
+    });
+  }
+}
+```
+
+Bind globally and DI-capable via `APP_FILTER`. Filters run last in the lifecycle, so they see anything thrown by guards, pipes, interceptors, or the handler.
+
+## Order when multiple are bound
+
+Within a kind, binding order is global → controller → route. Across kinds, the lifecycle order holds: guards → interceptors(pre) → pipes → handler → interceptors(post) → filters. A pipe cannot see what a later interceptor does; a guard cannot read a pipe-transformed DTO. When you need data shaped before authorization, that is a sign the work belongs in a guard's own context read, not downstream.

package/skills/nestjs/references/testing-recipes.md

@@ -0,0 +1,105 @@
+# Testing recipes
+
+The Nest-specific harness. For generic JS/TS test craft (runner config, coverage gates), that is `../../testing-web/SKILL.md`.
+
+## The harness
+
+`Test.createTestingModule({...})` builds a module exactly like a real `@Module`, then `.compile()` resolves it into a `TestingModule`. You pull instances with `.get(Token)` (singleton) or `.resolve(Token)` (scoped). Override providers, guards, interceptors, pipes, and filters before compiling.
+
+## Unit: mock a repository provider
+
+Unit-test a service in isolation — provide only the unit under test, mock its collaborators with `overrideProvider`.
+
+```typescript
+describe('OrdersService', () => {
+  let service: OrdersService;
+  const repo = { findById: vi.fn(), save: vi.fn() };
+
+  beforeEach(async () => {
+    const moduleRef = await Test.createTestingModule({
+      providers: [
+        OrdersService,
+        { provide: OrderRepository, useValue: repo },
+      ],
+    }).compile();
+
+    service = moduleRef.get(OrdersService);
+  });
+
+  it('returns the order', async () => {
+    repo.findById.mockResolvedValue({ id: '1', sku: 'A' });
+    await expect(service.get('1')).resolves.toMatchObject({ id: '1' });
+  });
+});
+```
+
+`overrideProvider(X).useValue(mock)` is the alternative when the provider is already declared by an imported module:
+
+```typescript
+const moduleRef = await Test.createTestingModule({ imports: [OrdersModule] })
+  .overrideProvider(OrderRepository)
+  .useValue(repo)
+  .compile();
+```
+
+## e2e: boot the app + Supertest
+
+e2e-test the wired app over HTTP. The trap: a `TestingModule` does **not** apply the globals you set in `main.ts`. Replicate them or the test diverges from production.
+
+```typescript
+describe('Orders (e2e)', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [AppModule],
+    })
+      .overrideGuard(AuthGuard)
+      .useValue({ canActivate: () => true }) // bypass auth for the route under test
+      .compile();
+
+    app = moduleRef.createNestApplication();
+    // MIRROR main.ts — without this, validation never runs in the test
+    app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }));
+    app.useGlobalFilters(new HttpExceptionFilter());
+    await app.init();
+  });
+
+  afterAll(async () => app.close());
+
+  it('rejects an unknown property', () =>
+    request(app.getHttpServer())
+      .post('/orders')
+      .send({ sku: 'A', quantity: 1, hacker: true })
+      .expect(400));
+});
+```
+
+## overrideGuard / override others
+
+`overrideGuard`, `overrideInterceptor`, `overridePipe`, `overrideFilter` mirror `overrideProvider`. Use them to neutralize auth or wrap-response behavior that would otherwise complicate the assertion.
+
+## Testing a request-scoped provider
+
+Singletons come from `.get()`; a request-scoped provider must come from `.resolve()`, which returns a Promise and gives a fresh instance per call (per DI sub-tree).
+
+```typescript
+const ctx = await moduleRef.resolve(RequestContext);
+```
+
+Each `resolve()` is a distinct instance — assert on the one you resolved, not on a `.get()` that would throw for a scoped provider.
+
+## ConfigModule in tests
+
+Provide config explicitly instead of relying on `.env` files leaking into CI:
+
+```typescript
+await Test.createTestingModule({
+  imports: [ConfigModule.forRoot({ ignoreEnvFile: true, load: [() => ({ JWT_SECRET: 'test' })] })],
+  providers: [AuthService],
+}).compile();
+```
+
+## Vitest vs Jest
+
+NestJS 11's harness moved toward **Vitest** (SWC-powered, fast), and these recipes use `vi.fn()`. Swap to `jest.fn()` if your project is on Jest — Jest is still fully supported and is what `nest new` scaffolds historically. The `Test.createTestingModule` API is identical under both.