nestjs-boost 0.0.0-stage → 1.2.0

package/skills/nestjs-deployment/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: nestjs-deployment
+description: Ships NestJS 12 applications to production — build and run (npm run build, node dist/main.js, NODE_ENV=production, PORT), Node.js 20.19+/22.12+ requirements, Dockerfile and .dockerignore with multi-stage builds, graceful shutdown with enableShutdownHooks, health checks, JSON logging and Observe instrumentation, vertical vs horizontal scaling behind load balancers, nest deploy with Mau on AWS, serverless functions on AWS Lambda (@codegenie/serverless-express, cached bootstrap, webpack bundling, lazy-loaded modules, standalone contexts, Swagger trailing-slash fix) and cold-start optimisation, and systemd socket activation with idle exit. Use when containerising or deploying an app, preparing it for production, running it on Lambda or another serverless platform, reducing cold starts, or setting up zero-downtime restarts. Not for health-check details (nestjs-health-checks), telemetry (nestjs-observability) or security headers and rate limits (nestjs-security-hardening).
+compatibility: NestJS 12.x; Node.js 20.19+ or 22.12+ (prefer active LTS); Docker, AWS Lambda/Serverless Framework, systemd as applicable
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# Deploying NestJS
+
+## Production baseline
+
+```bash
+npm run build                  # → dist/
+NODE_ENV=production node dist/main.js     # not `nest start` (it rebuilds) and not npm in containers (signals)
+```
+
+```typescript
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule, { bufferLogs: true });
+  app.enableShutdownHooks();                         // SIGTERM → onModuleDestroy/beforeApplicationShutdown/onApplicationShutdown
+  await app.listen(process.env.PORT ?? 3000, '0.0.0.0');
+}
+await bootstrap();
+```
+
+- **Node.js:** NestJS 12 requires Node.js 20.19+ or 22.12+; prefer an active LTS. Pin the version in the Docker base image and in `engines`.
+- **`NODE_ENV=production`:** some libraries behave differently with it.
+- **Config:** read config from the environment or a secrets manager, never hard-coded (see nestjs-configuration). Validate it at startup so a missing variable fails the deploy, not the first request.
+- **Health:** expose liveness and readiness probes (nestjs-health-checks) and point the load balancer or orchestrator at them.
+- **Logging:** use JSON logs in production (nestjs-logging).
+- **Telemetry:** `NestFactory.create(AppModule, { instrument: ObserveInstrument })` for NestJS Observe, or OpenTelemetry (nestjs-observability).
+- **Security:** helmet, CORS, rate limiting and body limits (nestjs-security-hardening).
+- **Process:** automate deploys with CI/CD and back up your data.
+
+## Scaling
+
+| Strategy | When | Requirements on the app |
+| --- | --- | --- |
+| Vertical (bigger machine) | Moderate traffic; simplest | — |
+| Horizontal (more instances behind a load balancer such as Nginx, ELB or Kubernetes) | High traffic, redundancy | **Stateless instances.** Sessions and cache go in Redis, not memory. Schedulers need distributed locks (nestjs-locks) or a single runner. WebSockets need the Redis adapter plus sticky sessions (nestjs-websockets). Uploads go to object storage (nestjs-file-storage). Run migrations once per deploy, not on every instance boot |
+
+## Docker
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM node:24-slim AS build                # match your project's Node version
+WORKDIR /usr/src/app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build && npm prune --omit=dev
+
+FROM node:24-slim
+ENV NODE_ENV=production
+WORKDIR /usr/src/app
+COPY --from=build /usr/src/app/node_modules ./node_modules
+COPY --from=build /usr/src/app/dist ./dist
+COPY package*.json ./
+USER node
+EXPOSE 3000
+CMD ["node", "dist/main"]                 # exec form: node is PID 1 and receives SIGTERM
+```
+
+`.dockerignore`: `node_modules`, `dist`, `*.log`, `*.md`, `.git`, `.env*`.
+
+Build with `docker build -t my-app .` and run with `docker run -p 3000:3000 my-app`. Push to Docker Hub, ECR or Artifact Registry.
+
+The docs' sample is a single stage (`npm install`, `npm run build`, `CMD ["node", "dist/main"]`). The multi-stage version above follows the same steps, ships without dev dependencies or sources, and runs as a non-root user.
+
+## Mau (official AWS platform)
+
+`nest deploy` (v12 CLI) offers to add `@nestjs/mau` and forwards options to `mau deploy`. In CI, use `npm i -g @nestjs/mau && mau deploy`, which doesn't prompt. Mau provisions databases (PostgreSQL, MySQL, DocumentDB, Redis) and brokers (RabbitMQ, Kafka, NATS). It also manages environment variables, horizontal scaling, health-check-based instance replacement, CloudWatch metrics and backups.
+
+## Serverless (AWS Lambda)
+
+```bash
+npm i @codegenie/serverless-express
+npm i -D @types/aws-lambda serverless-offline
+```
+
+```typescript
+let server: Handler;
+async function bootstrap(): Promise<Handler> {
+  const app = await NestFactory.create(AppModule);
+  await app.init();                                       // init, not listen
+  return configure({ app: app.getHttpAdapter().getInstance() });
+}
+export const handler: Handler = async (event, context, callback) => {
+  server = server ?? (await bootstrap());                 // reuse across warm invocations
+  return server(event, context, callback);
+};
+```
+
+- **`serverless.yml`:** `runtime: nodejs22.x`, `handler: dist/main.handler`, `http` events for `/` and `{proxy+}`. Run `npx serverless offline` and test at `/dev/<route>`.
+- **TypeScript:** set `esModuleInterop: true`.
+- **Bundle with webpack** (`externals: []`, `libraryTarget: 'commonjs2'`, Terser with `keep_classnames`). Mark the lazy optional imports (`@nestjs/microservices/microservices-module`, `@nestjs/websockets/socket-module`, …) with `IgnorePlugin`. Benchmarks: an Express-based Nest app drops from ~197 ms to ~81 ms, and a standalone context from ~112 ms to ~32 ms.
+- **CommonJS apps on Lambda's Node 20/22/24 runtimes** need `NODE_OPTIONS=--experimental-require-module`, because the v12 packages are ESM-only (nestjs-upgrading).
+- **Cold starts are dominated by your async providers** (for example DB connections). Load rarely used modules on demand with `LazyModuleLoader`, and split functions by job (monorepo mode).
+- **Non-HTTP handlers:** use `NestFactory.createApplicationContext(AppModule)` and `appContext.get(Service)`. This is lighter, but **no enhancers run**.
+- **Swagger behind API Gateway:** register middleware *before* `SwaggerModule.setup()` that rewrites `originalUrl` `/swagger` → `/swagger/`. Without it, the redirect loops forever.
+
+Details in `references/serverless-and-systemd.md`.
+
+## systemd socket activation (start on first connection, zero dropped connections across restarts)
+
+```typescript
+const activated = process.env.LISTEN_FDS === '1' && process.env.LISTEN_PID === String(process.pid);
+if (activated) await app.listen({ fd: 3 } as any);        // Fastify: app.listen({ fd: 3 }) is typed
+else await app.listen(process.env.PORT ?? 3000);
+```
+
+- Add a `.socket` unit (`ListenStream=3000`) and a `.service` unit (`ExecStart=/usr/bin/node dist/main.js`, `Restart=on-failure`).
+- Enable the socket only: `systemctl enable --now my-app.socket`.
+- **`ExecStart` must start `node` directly.** With npm, `nest start` or a shell wrapper, `LISTEN_PID` doesn't match, and the app fails with `EADDRINUSE`.
+- Not supported on Windows.
+- Optional idle exit frees memory (see the reference). Keep schedulers and queue consumers in an always-on process.
+
+## Workflow
+
+- [ ] 1. Validate config at startup, call `enableShutdownHooks()`, bind `0.0.0.0:$PORT`, use JSON logs, add health endpoints.
+- [ ] 2. Make the app stateless for horizontal scaling (shared cache and sessions, locks for cron, WebSocket adapter).
+- [ ] 3. Package: a multi-stage Docker image with a non-root `node` user and exec-form `CMD`, or the Lambda handler with a cached bootstrap and bundling, or systemd units.
+- [ ] 4. CI/CD: build, lint, test, build the image, run migrations once, deploy (`nest deploy` / `mau deploy` or your platform), and smoke-test the health endpoint.
+- [ ] 5. Locally: run the production build (`node dist/main.js` or `docker run`) and confirm graceful shutdown on SIGTERM.
+
+## Reference files
+
+- `references/serverless-and-systemd.md`: `serverless.yml`, the webpack config for Lambda, the standalone handler, the lazy-loading patterns, the systemd units, `systemd-socket-activate` for local trials, the idle-exit helper, and the compile-cache tip. Read when deploying to Lambda or systemd.
+
+Sources: [Deployment](https://docs.nestjs.com/deployment) · [Serverless](https://docs.nestjs.com/faq/serverless) · [Socket activation](https://docs.nestjs.com/recipes/socket-activation)

package/skills/nestjs-deployment/references/serverless-and-systemd.md

@@ -0,0 +1,133 @@
+# Serverless and systemd details
+
+## Contents
+- serverless.yml
+- Bundling with webpack
+- Standalone handlers
+- Runtime optimisations
+- systemd units
+- Idle exit and compile cache
+
+## serverless.yml
+
+```yaml
+service: serverless-example
+plugins:
+  - serverless-offline
+provider:
+  name: aws
+  runtime: nodejs22.x
+functions:
+  main:
+    handler: dist/main.handler
+    events:
+      - http: { method: ANY, path: / }
+      - http: { method: ANY, path: '{proxy+}' }
+```
+
+Test locally with `npm run build && npx serverless offline`, then open `http://localhost:3000/dev/<route>`. Set `"esModuleInterop": true` in `tsconfig.json`. Use CLI monorepo mode for several functions that share modules.
+
+## Bundling with webpack
+
+`webpack.config.js` in the project root; build with `nest build --webpack`:
+
+```javascript
+const TerserPlugin = require('terser-webpack-plugin');   // optional; slows the build
+
+module.exports = (options, webpack) => {
+  const lazyImports = ['@nestjs/microservices/microservices-module', '@nestjs/websockets/socket-module'];
+  return {
+    ...options,
+    externals: [],                                         // bundle node_modules
+    output: { ...options.output, libraryTarget: 'commonjs2' },
+    optimization: { minimizer: [new TerserPlugin({ terserOptions: { keep_classnames: true } })] },   // class-validator needs class names
+    plugins: [
+      ...options.plugins,
+      new webpack.IgnorePlugin({
+        checkResource(resource) {
+          if (lazyImports.includes(resource)) {
+            try { require.resolve(resource); } catch { return true; }
+          }
+          return false;
+        },
+      }),
+    ],
+  };
+};
+```
+
+Docs benchmarks (starter app): Express ~7 ms; Nest/Express 197 ms unbundled → 81.5 ms bundled; standalone context 112 ms → 32 ms. An app with 10 resources takes ~130 ms bundled.
+
+## Standalone handlers
+
+```typescript
+export const handler: Handler = async (event, context, callback) => {
+  const appContext = await NestFactory.createApplicationContext(AppModule);
+  return appContext.get(EventsService).process(event);    // no guards/interceptors/pipes (no HTTP layer)
+};
+```
+
+Cache the context in a module-level variable, as with the HTTP handler, to reuse it on warm invocations.
+
+## Runtime optimisations
+
+- Async providers that connect on boot add their latency to every cold start. A 2 s DB connection means at least 2 s extra on the first response.
+- Load rarely used modules lazily:
+
+```typescript
+if (request.method === RequestMethod[RequestMethod.GET]) {
+  const { CacheModule } = await import('./cache.module.js');
+  const moduleRef = await this.lazyModuleLoader.load(() => CacheModule);
+  const { CacheService } = await import('./cache.service.js');
+  return moduleRef.get(CacheService).get(ENDPOINT_KEY);
+}
+```
+
+- Use the same pattern for workers or webhooks that branch on input (load `WorkerAModule` or `WorkerBModule` on demand).
+- Swagger UI behind API Gateway: `app.use((req, res, next) => { if (req.originalUrl === '/swagger') req.originalUrl = '/swagger/'; next(); })` before `SwaggerModule.setup()`.
+
+## systemd units
+
+```ini
+# /etc/systemd/system/my-app.socket
+[Socket]
+ListenStream=3000
+[Install]
+WantedBy=sockets.target
+
+# /etc/systemd/system/my-app.service
+[Service]
+WorkingDirectory=/srv/my-app
+ExecStart=/usr/bin/node dist/main.js
+Restart=on-failure
+```
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now my-app.socket       # the service starts on the first connection
+systemd-socket-activate --listen=3000 --setenv=NODE_ENV node dist/main.js   # quick local trial (starts once)
+```
+
+systemd passes fd 3 and sets `LISTEN_FDS`/`LISTEN_PID`. Connections that arrive during a start or restart wait in the socket backlog instead of being refused. Express and the Node adapter pass `{ fd: 3 }` straight to `server.listen()`, but their typings need `as any`.
+
+## Idle exit and compile cache
+
+```typescript
+export function exitWhenIdle(app: INestApplication, idleMs: number) {
+  const server: Server = app.getHttpServer();
+  let inFlight = 0;
+  let timer: NodeJS.Timeout | undefined;
+  const scheduleExit = () => { timer = setTimeout(async () => { await app.close(); process.exit(0); }, idleMs); };
+  server.on('request', (req, res) => {
+    inFlight++; clearTimeout(timer);
+    res.once('close', () => { if (--inFlight === 0) scheduleExit(); });
+  });
+  scheduleExit();
+}
+// if (activated) { await app.listen({ fd: 3 } as any); exitWhenIdle(app, 5 * 60_000); }
+```
+
+- Use `Restart=on-failure`. With `Restart=always`, the app restarts immediately after an idle exit.
+- Uptime monitors and health probes keep the app awake.
+- Cron jobs and queue consumers don't run while the app is stopped.
+- The first request waits for the full bootstrap. Speed up restarts with Node's compile cache: add `Environment=NODE_COMPILE_CACHE=/var/cache/my-app` and `CacheDirectory=my-app` to the service unit. The cache is written on exit, so `enableShutdownHooks()` is required for SIGTERM.

package/skills/nestjs-events/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: nestjs-events
+description: Decouples NestJS 12 modules with in-process events using @nestjs/event-emitter (EventEmitter2) — EventEmitterModule.forRoot options, emitting typed event classes with EventEmitter2.emit/emitAsync, @OnEvent listeners with async, prependListener and suppressErrors options, namespaces and wildcards (order.*, **), request-scoped listeners, avoiding lost events at startup with EventEmitterReadinessWatcher, and testing emitters and listeners. Use when one module should react to something another module did (send a welcome email after sign-up, update stats after an order) without a direct dependency, or when listeners don't fire, errors vanish or startup events are missed. Not for durable/cross-process messaging (nestjs-outbox, nestjs-queues, nestjs-microservices), CQRS buses (nestjs-cqrs) or real-time client push (nestjs-websockets, SSE in nestjs-http-web-features).
+compatibility: NestJS 12.x; @nestjs/event-emitter
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# NestJS events (@nestjs/event-emitter)
+
+In-process, fire-and-forget, **not durable**: events are lost if the process crashes or a listener throws. If the reaction must happen (emails, webhooks, other services), write it to the outbox (nestjs-outbox) or a queue (nestjs-queues) in the same transaction instead.
+
+```bash
+npm i @nestjs/event-emitter
+```
+
+## Setup
+
+```typescript
+@Module({ imports: [EventEmitterModule.forRoot({ wildcard: true, delimiter: '.', maxListeners: 20 })] })
+export class AppModule {}
+```
+
+Registered globally. Listeners are registered in `onApplicationBootstrap`. Other options: `newListener`, `removeListener`, `verboseMemoryLeak`, `ignoreErrors`.
+
+## Emit and listen
+
+```typescript
+// orders/events/order-created.event.ts
+export class OrderCreatedEvent {
+  static readonly name = 'order.created';     // keep event names in one place
+  constructor(readonly orderId: string, readonly userId: string) {}
+}
+
+// orders/orders.service.ts
+constructor(private readonly events: EventEmitter2) {}
+async create(dto: CreateOrderDto) {
+  const order = await this.repo.create(dto);
+  this.events.emit(OrderCreatedEvent.name, new OrderCreatedEvent(order.id, dto.userId));
+  return order;
+}
+
+// notifications/order-listener.ts
+@Injectable()
+export class OrderCreatedListener {
+  private readonly logger = new Logger(OrderCreatedListener.name);
+  @OnEvent(OrderCreatedEvent.name, { async: true })
+  async handle(event: OrderCreatedEvent) { await this.mailer.sendReceipt(event.orderId); }
+}
+```
+
+- Listener classes must be providers of a module that's loaded.
+- `emit()` returns immediately with sync listeners run inline; `emitAsync()` returns a promise of all listener results (use when the caller must wait).
+- `@OnEvent` options: `async`, `prependListener`, `suppressErrors` (default **true**: errors are logged, not rethrown), plus EventEmitter2 `OnOptions`.
+- Emit after the transaction commits; emitting inside it notifies listeners about data that may roll back.
+- Wildcards (with `wildcard: true`): `order.*` matches one segment; `**` matches all. Events can be arrays (`['order', 'created']`).
+- Request-scoped listener providers get a new instance per event; `REQUEST` resolves to the payload.
+
+## Startup events
+
+Events emitted from constructors or `onModuleInit` can be lost. In `onApplicationBootstrap`, `await this.readiness.waitUntilReady()` (`EventEmitterReadinessWatcher`) before emitting.
+
+## Testing
+
+- Emitter: provide `{ provide: EventEmitter2, useValue: { emit: vi.fn() } }` and assert the event name and payload.
+- Listener: call the method directly with an event instance.
+- Integration: import `EventEmitterModule.forRoot()` in the testing module, call `app.init()` (listeners register on bootstrap), emit with `emitAsync()` and await.
+
+## Workflow
+
+- [ ] 1. Install; `EventEmitterModule.forRoot()` in `AppModule`.
+- [ ] 2. Define event classes with a name constant; emit after commit.
+- [ ] 3. Add listener providers with `@OnEvent`; decide `async` and error handling (log + metrics; don't rely on suppressed errors silently).
+- [ ] 4. Tests for emit + listener. Build, lint, run tests, start the app.
+
+Sources: [Events](https://docs.nestjs.com/application/events)

package/skills/nestjs-file-storage/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: nestjs-file-storage
+description: Stores files in NestJS 12 with the first-party @nestjs/storage package — named disks (LocalDisk for development, S3Disk for AWS S3, Cloudflare R2, MinIO, Backblaze B2, GCS; InMemoryDisk for tests) behind one API (put/get/stat/list/delete/copy/move), StorageModule.forRootAsync from config, @InjectDisk and the Storage registry, streaming Multer uploads straight to a disk with uploadToDisk() and content sniffing, public URLs, short-lived signed download URLs, presigned direct uploads with signedUpload(), serveFile/serveSignedUrl/receiveSignedUpload helpers, key safety, and storage errors. Use when the user needs to save uploads, product images, invoices or user files, generate download links, upload directly from clients to S3/R2, or switch between local and cloud storage. Not for parsing multipart requests themselves (nestjs-http-web-features) or static frontend hosting (serve-static in nestjs-http-web-features).
+compatibility: NestJS 12.x; @nestjs/storage (no AWS SDK needed); @nestjs/config
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# NestJS file storage (@nestjs/storage)
+
+Use `@nestjs/storage` instead of hand-written `fs` writes or the AWS SDK: same code for local and S3, atomic writes, signed URLs, content sniffing.
+
+```bash
+npm i @nestjs/storage @nestjs/config
+```
+
+## Disks from configuration
+
+```typescript
+export function createStorageOptions(config: ConfigService): StorageModuleOptions {
+  if (config.get('storage.driver') === 's3') {
+    const s3 = { endpoint: config.get<string>('storage.s3.endpoint'), region: config.getOrThrow<string>('storage.s3.region') };
+    return {
+      default: 'private',
+      disks: {
+        photos: new S3Disk({ ...s3, bucket: config.getOrThrow('storage.s3.photosBucket'), publicUrl: config.getOrThrow('storage.s3.photosUrl') }),
+        private: new S3Disk({ ...s3, bucket: config.getOrThrow('storage.s3.privateBucket') }),
+      },
+    };
+  }
+  const appUrl = config.getOrThrow<string>('appUrl');
+  return {
+    default: 'private',
+    disks: {
+      photos: new LocalDisk({ root: 'storage/photos', publicUrl: `${appUrl}/photos` }),
+      private: new LocalDisk({ root: 'storage/private', signedUrls: { baseUrl: `${appUrl}/files`, keys: [config.getOrThrow('storage.signingKey')] } }),   // key ≥32 chars
+    },
+  };
+}
+
+StorageModule.forRootAsync({ inject: [ConfigService], useFactory: createStorageOptions }),
+```
+
+- Separate disks (buckets) for public and private files — there is no per-file public flag.
+- Inject: `StorageDisk` (default disk), `@InjectDisk('photos') photos: StorageDisk`, or `Storage` (`storage.disk(name)`). Misnamed disks fail at startup.
+- `S3Disk` reads `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`/`AWS_SESSION_TOKEN` (or `credentials`). R2: `endpoint: 'https://<account>.r2.cloudflarestorage.com', region: 'auto'`; MinIO: `forcePathStyle: true`; GCS: `batchDelete: false`.
+- Never `LocalDisk` in production (container disks vanish, instances don't share).
+
+## Stream uploads onto a disk
+
+```typescript
+@Post('products/:id/photo')
+@UseInterceptors(FileInterceptor('photo', {
+  storage: uploadToDisk({ disk: 'photos', contentTypes: ['image/jpeg', 'image/png', 'image/webp'], cacheControl: 'public, max-age=31536000, immutable' }),
+  limits: { fileSize: 5 * 1024 * 1024, files: 1 },
+}))
+async upload(@Param('id') id: string, @UploadedFile() file: StoredUpload | undefined) {
+  if (!file) throw new BadRequestException('Attach the image as the "photo" field');
+  return this.photosService.replace(id, file.key);      // delete file.key if the product doesn't exist
+}
+```
+
+- `uploadToDisk()` sniffs the real type from the bytes (415 if not allowed), enforces the size without leaving partial files (413), and picks a random UUID key with the detected extension. Use `file.contentType`, not the client's `mimetype`.
+- `ParseFilePipe`/`FileTypeValidator` run after the file is stored — validate in the engine instead.
+- Formats without a signature (CSV): `detectContentType: (bytes) => …` returning a type in `contentTypes`; still validate the whole file afterwards.
+- Custom keys: `key: (file) => \`price-lists/${randomUUID()}${file.extension}\``. Build keys from ids you control.
+
+## Private files and signed URLs
+
+```typescript
+const key = `invoices/${order.id}.pdf`;
+if (!(await this.disk.exists(key))) await this.disk.put(key, pdfBuffer, { contentType: 'application/pdf', metadata: { orderId: order.id } });
+return { url: await this.disk.signedUrl(key, { expiresIn: '5m', filename: `invoice-${order.id}.pdf` }) };
+```
+
+- Check ownership/authorization before issuing links (nestjs-authorization). Signed URLs can't be revoked: keep them short (default 15 min, max 7 days).
+- Local disks: add a `FilesController` with `@Get() serveSignedUrl(disk, { req, res })` and `@Put() receiveSignedUpload(disk, { req, res })` under the `signedUrls.baseUrl` route (404 with S3, which serves presigned URLs itself).
+- Public files: `disk.url(key)` (under `publicUrl`, usually a CDN); dev route: `serveFile(disk, key, { req, res, disposition: 'inline' })`.
+
+## Direct uploads from clients
+
+1. `POST …/uploads` → `uploads.signedUpload(\`incoming/${productId}/${randomUUID()}\`, { contentType, contentLength: size, expiresIn: '10m' })` returns `{ url, method: 'PUT', headers, expiresAt }`.
+2. Client `PUT`s the file.
+3. `PUT …/photo { key }` → verify the key prefix you issued, `stat()` the size, ranged `get(key, { range: { start: 0, end: 15 } })` + `detectContentType()`, then stream `get()` → `put()` onto the public disk and delete the incoming file.
+
+Expire `incoming/` and incomplete multipart uploads with bucket lifecycle rules; enable bucket CORS for browser PUTs.
+
+## Testing
+
+```typescript
+const photos = new InMemoryDisk({ publicUrl: 'https://photos.example.com' });
+const files = new InMemoryDisk({ signedUrls: { baseUrl: 'https://api.example.com/files', keys: ['test-signing-key-0123456789abcdef'] } });
+// .overrideProvider(STORAGE_MODULE_OPTIONS).useValue({ default: 'private', disks: { photos, private: files } })
+expect(photos.keys()).toHaveLength(1);   // photos.getBuffer(key), photos.clear()
+```
+
+## Workflow
+
+- [ ] 1. Install; config file with driver/buckets/signing key; `createStorageOptions` factory; `StorageModule.forRootAsync`.
+- [ ] 2. Uploads via `FileInterceptor` + `uploadToDisk()` with types, size and cache headers.
+- [ ] 3. Private files with signed URLs after authorization; dev `FilesController`.
+- [ ] 4. Direct uploads if clients send large files; lifecycle rules, CORS, least-privilege IAM (`GetObject`, `PutObject`, `DeleteObject`, `ListBucket`).
+- [ ] 5. InMemoryDisk e2e tests. Build, lint, run tests, start the app.
+
+## Reference files
+
+- `references/storage-reference.md`: disk methods and key rules, disk options (S3 encryption, multipart, retries), HTTP helper options, errors with statuses, Fastify raw-body note. Read when using methods beyond the basics or mapping errors.
+
+Sources: [File storage](https://docs.nestjs.com/application/file-storage)

package/skills/nestjs-file-storage/references/storage-reference.md

@@ -0,0 +1,82 @@
+# @nestjs/storage reference
+
+## Contents
+- Module options
+- Keys
+- Disk methods
+- Disks
+- HTTP helpers
+- Errors
+- Notes
+
+## Module options
+
+`StorageModule.forRoot()` / `forRootAsync()` (factory returns `default` + disk instances; disk classes, `imports`, `isGlobal` beside `useFactory`). Token: `STORAGE_MODULE_OPTIONS`.
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `disks` | required | name → instance or injectable `StorageDisk` class |
+| `default` | the only disk | required with more than one disk |
+| `imports` | none | for disk classes |
+| `isGlobal` | `true` | registers `Storage`, `StorageDisk`, named disks |
+
+## Keys
+
+Relative `/`-separated paths ≤1024 UTF-8 bytes; no empty, `.` or `..` segments, backslashes or control characters. Enforced on every disk, so user input can't escape a disk — but it can name any file on it.
+
+## Disk methods
+
+| Method | Notes |
+| --- | --- |
+| `put(key, body, { contentType, cacheControl, contentDisposition, metadata (≤2 KB strings), contentLength, signal })` | atomic; body: Buffer, string, Uint8Array, Node/web stream, async iterable → `{ key, size, contentType, etag }` |
+| `get(key, { range: { start, end } \| { suffix } })` | metadata + `body` (Node stream) |
+| `getBuffer(key)`, `getText(key)` | whole file |
+| `stat(key)`, `exists(key)` | metadata only / boolean |
+| `delete(key \| keys[])` | missing keys ignored |
+| `list({ prefix, cursor, limit ≤1000 })`, `listAll(opts)` | pages of `key`, `size`, `lastModified`, `etag` |
+| `copy(from, to)`, `move(from, to)` | within the disk, metadata included |
+| `url(key)` | public URL; throws without `publicUrl` |
+| `signedUrl(key, { expiresIn, filename, disposition })` | default 15 min, max 7 days |
+| `signedUpload(key, { contentType, contentLength, expiresIn })` | `{ url, method, headers, expiresAt }`; signed for exact type and length |
+
+## Disks
+
+| Disk | Options |
+| --- | --- |
+| `LocalDisk` | `root` (created at startup), `publicUrl`, `signedUrls`; `path(key)` |
+| `S3Disk` | `bucket`, `region` (`AWS_REGION` → `AWS_DEFAULT_REGION` → `us-east-1`), `endpoint`, `forcePathStyle`, `credentials` (object or function), `prefix`, `serverSideEncryption` (`'aws:kms'`), `kmsKeyId`, `multipart`, `retry`, `timeout`, `batchDelete`, `fetch`, `publicUrl` |
+| `InMemoryDisk` | `publicUrl`, `signedUrls`; `keys()`, `clear()` |
+
+`signedUrls: { baseUrl, keys }` — keys ≥32 chars, first signs, all verify (rotate by prepending). S3 uploads >8 MiB (or unknown length) go multipart (8 MiB parts, 4 at a time), aborted on failure. SigV4 implemented on `node:crypto`.
+
+## HTTP helpers
+
+| Helper | Options |
+| --- | --- |
+| `uploadToDisk(opts)` | `disk`, `contentTypes`, `detectContentType`, `contentTypeSampleBytes` (4 KiB default, 1 B–64 KiB), `cacheControl`, `key(file, req)`, `metadata(file, req)` → `StoredUpload` (`key`, `disk`, `contentType`, `etag` + multer fields) |
+| `serveFile(disk, key, { res, req, disposition, filename, cacheControl })` | Range and If-None-Match with `req`; sets `X-Content-Type-Options: nosniff` |
+| `serveSignedUrl(disk, { req, res, cacheControl })` | verifies signature, expiry, method |
+| `receiveSignedUpload(disk, { req, res, maxSize })` | verifies and streams the PUT body |
+| `detectContentType(bytes)` | JPEG, PNG, GIF, WebP, AVIF, HEIC, PDF from first 16 bytes |
+
+Fastify: the upload body must reach `receiveSignedUpload` unparsed — register a catch-all content-type parser that leaves the body alone.
+
+## Errors
+
+All extend `StorageError` (not `HttpException` outside the helpers — map them yourself):
+
+| Error | status |
+| --- | --- |
+| `StorageFileNotFoundError` (`key`) | 404 |
+| `StorageInvalidKeyError` (`reason`) | 400 |
+| `StorageBodyLengthError` (`expected`, `received`) | 400 |
+| `StorageRangeNotSatisfiableError` (`size`) | 416 |
+| `StorageKeyConflictError` (local disk `a` vs `a/b`) | 409 |
+| `StorageSignedUrlError` (`missing`, `invalid`, `expired`, `method`) | 403 |
+| `StorageServiceError` (`code`, `upstreamStatus`, `requestId`, `operation`) | — |
+
+## Notes
+
+- IAM: keep `s3:ListBucket`, or missing files return 403 and `exists()` throws.
+- Local disks keep temp files and metadata in `.nest-storage`.
+- To test real S3 behaviour (presigned URLs, multipart) point `S3Disk` at a local MinIO.

package/skills/nestjs-graphql/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: nestjs-graphql
+description: Builds GraphQL APIs with NestJS 12 and @nestjs/graphql v14 — Apollo Server 5 (@nestjs/apollo) or Mercurius drivers, code-first (@ObjectType, @Field, @Resolver, @Query, @Mutation, @ResolveField, @Args, @InputType, @ArgsType) or schema-first (typePaths, generated definitions), GraphiQL (playground removed), context with req/res, subscriptions over graphql-ws with PubSub, filters and onConnect auth, custom scalars, directives, interfaces, unions and enums, field middleware, mapped types, Apollo plugins and query complexity, extensions, the GraphQL CLI plugin, schema generation, sharing models, guards/interceptors/filters with GqlExecutionContext, fieldResolverEnhancers, and Apollo/Mercurius Federation 1 and 2 with subgraphs and gateways. Use when adding or debugging a GraphQL endpoint, resolvers, types, subscriptions, federation, or migrating from playground/subscriptions-transport-ws/Apollo Server 4. Not for REST/OpenAPI (nestjs-openapi) or WebSocket gateways (nestjs-websockets).
+compatibility: NestJS 12.x; @nestjs/graphql v14, @nestjs/apollo v14 (Apollo Server v5) or @nestjs/mercurius; graphql
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# NestJS GraphQL
+
+## Install and register
+
+```bash
+npm i @nestjs/graphql @nestjs/apollo @apollo/server @as-integrations/express5 graphql   # Express/Node adapter
+# Fastify + Apollo: @as-integrations/fastify instead;  Fastify + Mercurius: @nestjs/graphql @nestjs/mercurius graphql mercurius
+```
+
+```typescript
+GraphQLModule.forRootAsync<ApolloDriverConfig>({
+  driver: ApolloDriver,
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    autoSchemaFile: join(process.cwd(), 'src/schema.gql'),   // code first; `true` = in memory
+    sortSchema: true,
+    graphiql: config.get('NODE_ENV') !== 'production',        // GraphiQL (playground was removed in v14)
+    context: ({ req, res }) => ({ req, res }),                // a FUNCTION: per-request context
+    subscriptions: { 'graphql-ws': true },
+  }),
+}),
+```
+
+- `@nestjs/apollo` v14 requires Apollo Server v5 (`@apollo/server`). `playground` is only a deprecated boolean alias for `graphiql`. `subscriptions-transport-ws` support is removed — use `graphql-ws`.
+- Detect the project's approach (code first: `autoSchemaFile`; schema first: `typePaths`) and stay with it.
+- Node adapter: use the Apollo driver; Mercurius requires Fastify.
+
+## Code first essentials
+
+```typescript
+@ObjectType({ description: 'Author' })
+export class Author {
+  @Field(() => ID) id: string;
+  @Field({ nullable: true }) firstName?: string;
+  @Field(() => [Post]) posts: Post[];
+}
+
+@InputType()
+export class CreatePostInput {
+  @Field() @MinLength(3) title: string;
+  @Field(() => Int, { nullable: true }) votes?: number;
+}
+
+@ArgsType()
+export class GetAuthorArgs {
+  @Field(() => ID) id: string;
+}
+
+@Resolver(() => Author)
+export class AuthorsResolver {
+  constructor(private readonly authors: AuthorsService, private readonly posts: PostsService) {}
+
+  @Query(() => Author, { name: 'author', nullable: true })
+  author(@Args() { id }: GetAuthorArgs) { return this.authors.findOne(id); }
+
+  @Mutation(() => Post)
+  createPost(@Args('input') input: CreatePostInput) { return this.posts.create(input); }
+
+  @ResolveField('posts', () => [Post])
+  posts(@Parent() author: Author) { return this.posts.findByAuthor(author.id); }   // batch with DataLoader to avoid N+1
+}
+```
+
+- Types need explicit `() => Int | Float | ID | [Type]` where TypeScript reflection can't tell (numbers, arrays, nullables); or enable the GraphQL CLI plugin (`"plugins": ["@nestjs/graphql"]`, files `*.input.ts`, `*.args.ts`, `*.entity.ts`, `*.model.ts`).
+- Arrays/nullability: `nullable: 'items' | 'itemsAndList'`.
+- Validation: a global `ValidationPipe` (or `StandardSchemaValidationPipe`) validates `@Args` classes.
+- Derive input types with `PartialType`, `PickType`, `OmitType`, `IntersectionType` from **`@nestjs/graphql`**.
+- `@Resolver` on methods isn't supported in code first. Register resolvers as providers.
+- Scaffold with `nest g resource` (GraphQL code first option).
+
+## Subscriptions
+
+```typescript
+{ provide: PUB_SUB, useValue: new PubSub() }       // graphql-subscriptions; in-memory — use a Redis-backed PubSub with several instances
+
+@Subscription(() => Comment, { filter: (payload, vars) => payload.commentAdded.postId === vars.postId })
+commentAdded(@Args('postId') postId: string) { return this.pubSub.asyncIterableIterator('commentAdded'); }
+
+// in a mutation
+await this.pubSub.publish('commentAdded', { commentAdded: comment });   // payload shape: { <subscriptionName>: value } unless `resolve` is used
+```
+
+Authenticate in `subscriptions['graphql-ws'].onConnect(ctx)` (read `ctx.connectionParams`, store the user on `ctx.extra`) and build `context: ({ req, extra }) => …`. Custom server: pass `server: new WebSocketServer({ noServer: true, path })`.
+
+## Guards, interceptors, filters
+
+- Convert contexts: `GqlExecutionContext.create(context).getContext().req` in guards/interceptors/param decorators; `GqlArgumentsHost.create(host)` in filters implementing `GqlExceptionFilter` (return/throw the error; there is no response object).
+- Global enhancers run on root resolvers (Query/Mutation/Subscription) only. `fieldResolverEnhancers: ['guards', 'interceptors', 'filters']` enables them for field resolvers — costly on large lists.
+- `CacheInterceptor` doesn't work in GraphQL (runs per field).
+- With `@nestjs/authentication` / `@nestjs/authorization`, see those skills for the context setup.
+
+## Hardening
+
+Limit query cost with an Apollo `@Plugin()` using `graphql-query-complexity` (`fieldExtensionsEstimator` + `simpleEstimator`, `complexity` on fields; see `references/schema-features.md`); disable GraphiQL on public non-production hosts.
+
+## Workflow
+
+- [ ] 1. Install the driver set for the adapter; register `GraphQLModule` with config-driven options.
+- [ ] 2. Model types/inputs/args; resolvers + services per domain module; validation pipe.
+- [ ] 3. Field resolvers with batching; subscriptions with a shared PubSub provider; auth in context/onConnect.
+- [ ] 4. Complexity limits; error formatting; enhancers where needed.
+- [ ] 5. E2E tests: `request(app.getHttpServer()).post('/graphql').send({ query, variables })` and assert `data`/`errors`. Build, lint, run tests, start the app and open GraphiQL.
+
+## Reference files
+
+- `references/schema-features.md`: schema first setup and typings generation, scalars (date/number modes, custom), directives, interfaces (`resolveType`, `inheritResolversFromInterfaces`), unions/enums, field middleware, extensions, mapped types, CLI plugin, SDL generation, sharing models, multiple endpoints, Mercurius. Read when using any of these.
+- `references/federation.md`: Apollo and Mercurius federation (subgraph drivers, `@key`/`@ResolveReference`/`@extends`, Federation 2, gateway with `IntrospectAndCompose`, `@inaccessible`, subscriptions caveat). Read when building subgraphs or gateways.
+
+Sources: [Quick start](https://docs.nestjs.com/graphql/quick-start) · [Resolvers](https://docs.nestjs.com/graphql/resolvers) · [Mutations](https://docs.nestjs.com/graphql/mutations) · [Subscriptions](https://docs.nestjs.com/graphql/subscriptions) · [Scalars](https://docs.nestjs.com/graphql/scalars) · [Directives](https://docs.nestjs.com/graphql/directives) · [Interfaces](https://docs.nestjs.com/graphql/interfaces) · [Unions and enums](https://docs.nestjs.com/graphql/unions-and-enums) · [Field middleware](https://docs.nestjs.com/graphql/field-middleware) · [Mapped types](https://docs.nestjs.com/graphql/mapped-types) · [Plugins](https://docs.nestjs.com/graphql/plugins) · [Complexity](https://docs.nestjs.com/graphql/complexity) · [Extensions](https://docs.nestjs.com/graphql/extensions) · [CLI plugin](https://docs.nestjs.com/graphql/cli-plugin) · [Generating SDL](https://docs.nestjs.com/graphql/generating-sdl) · [Sharing models](https://docs.nestjs.com/graphql/sharing-models) · [Other features](https://docs.nestjs.com/graphql/other-features) · [Federation](https://docs.nestjs.com/graphql/federation)