spoonfeeder 0.1.0

package/templates/recipes/docker-compose-dev/docker-compose.dev.yml.ejs

@@ -0,0 +1,54 @@
+version: '3.8'
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    ports:
+      - '${PORT:-3000}:3000'
+      - '9229:9229'
+    volumes:
+      - .:/app
+      - /app/node_modules
+    env_file: .env
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    command: pnpm start:debug
+
+  postgres:
+    image: postgres:16-alpine
+    ports:
+      - '5432:5432'
+    environment:
+      POSTGRES_USER: ${DB_USERNAME:-dev}
+      POSTGRES_PASSWORD: ${DB_PASSWORD:-dev}
+      POSTGRES_DB: ${DB_NAME:-<%= name %>}
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U ${DB_USERNAME:-dev}']
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - '6379:6379'
+    healthcheck:
+      test: ['CMD', 'redis-cli', 'ping']
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  adminer:
+    image: adminer
+    ports:
+      - '8080:8080'
+
+volumes:
+  pgdata:

package/templates/recipes/docs-site/README.md

@@ -0,0 +1,41 @@
+# Documentation Site
+
+VitePress-powered documentation site for project documentation.
+
+## Links
+
+- [VitePress Documentation](https://vitepress.dev)
+- [VitePress on npm](https://www.npmjs.com/package/vitepress)
+- [VitePress on GitHub](https://github.com/vuejs/vitepress)
+
+## Dependencies
+
+| Package     | Version | Purpose                                 |
+| ----------- | ------- | --------------------------------------- |
+| `vitepress` | `1.6.3` | Static site generator for documentation |
+
+## Usage
+
+Add scripts to `package.json`:
+
+```json
+{
+  "scripts": {
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  }
+}
+```
+
+Start the docs dev server:
+
+```bash
+pnpm docs:dev
+```
+
+## Generated Files
+
+| File                            | Description                      |
+| ------------------------------- | -------------------------------- |
+| `docs/.vitepress/config.ts.ejs` | VitePress configuration template |

package/templates/recipes/docs-site/docs/.vitepress/config.ts.ejs

@@ -0,0 +1,53 @@
+import { defineConfig } from 'vitepress';
+
+export default defineConfig({
+  title: '<%= projectName %>',
+  description: '<%= projectDescription %>',
+  base: '/<%= repoName %>/',
+  themeConfig: {
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Guide', link: '/guide/' },
+      { text: 'API Reference', link: '/api/' },
+    ],
+    sidebar: {
+      '/guide/': [
+        {
+          text: 'Getting Started',
+          items: [
+            { text: 'Introduction', link: '/guide/' },
+            { text: 'Installation', link: '/guide/installation' },
+            { text: 'Configuration', link: '/guide/configuration' },
+          ],
+        },
+        {
+          text: 'Architecture',
+          items: [
+            { text: 'Project Structure', link: '/guide/structure' },
+            { text: 'Modules', link: '/guide/modules' },
+          ],
+        },
+      ],
+      '/api/': [
+        {
+          text: 'API Reference',
+          items: [
+            { text: 'Overview', link: '/api/' },
+            { text: 'Authentication', link: '/api/authentication' },
+            { text: 'Endpoints', link: '/api/endpoints' },
+          ],
+        },
+      ],
+    },
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/<%= githubOrg %>/<%= repoName %>' },
+    ],
+    search: {
+      provider: 'local',
+    },
+    editLink: {
+      pattern: 'https://github.com/<%= githubOrg %>/<%= repoName %>/edit/main/docs/:path',
+      text: 'Edit this page on GitHub',
+    },
+  },
+});

package/templates/recipes/dpop/README.md

@@ -0,0 +1,37 @@
+# DPoP (Demonstrating Proof of Possession)
+
+Implements [RFC 9449 — OAuth 2.0 Demonstrating Proof of Possession (DPoP)](https://datatracker.ietf.org/doc/html/rfc9449) for binding access tokens to a client's key pair.
+
+## How it works
+
+`DPoPGuard` validates the `DPoP` proof JWT on protected endpoints. It checks:
+
+- The proof JWT type is `dpop+jwt`
+- The `htm` claim matches the HTTP method
+- The `htu` claim matches the request URI
+- The proof is not older than 300 seconds
+- The `jwk` in the proof header is used to verify the signature
+
+## Setup
+
+Apply the guard to routes that require proof-of-possession tokens:
+
+```typescript
+import { DPoPGuard } from '@/shared/guards/dpop.guard';
+
+@UseGuards(DPoPGuard)
+@Get('protected')
+getProtected() {
+  return { message: 'Access granted with DPoP' };
+}
+```
+
+Clients must:
+
+1. Use the `DPoP` authorization scheme: `Authorization: DPoP <access_token>`
+2. Include a `DPoP` header with a signed `dpop+jwt` proof
+
+## References
+
+- [RFC 9449 — OAuth 2.0 Demonstrating Proof of Possession (DPoP)](https://datatracker.ietf.org/doc/html/rfc9449)
+- [jose](https://www.npmjs.com/package/jose) — JavaScript module for JSON Object Signing and Encryption

package/templates/recipes/dpop/src/shared/guards/dpop.guard.ts

@@ -0,0 +1,61 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  UnauthorizedException,
+  Logger,
+} from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { FastifyRequest } from 'fastify';
+import * as jose from 'jose';
+
+@Injectable()
+export class DPoPGuard implements CanActivate {
+  private readonly logger = new Logger(DPoPGuard.name);
+
+  constructor(private readonly configService: ConfigService) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = context.switchToHttp().getRequest<FastifyRequest>();
+    const dpopHeader = request.headers['dpop'] as string | undefined;
+    const authHeader = request.headers.authorization;
+
+    if (!dpopHeader) {
+      throw new UnauthorizedException('Missing DPoP proof header');
+    }
+
+    if (!authHeader?.startsWith('DPoP ')) {
+      throw new UnauthorizedException('Authorization header must use DPoP scheme');
+    }
+
+    try {
+      const { protectedHeader, payload } = await jose.jwtVerify(
+        dpopHeader,
+        async (header) => {
+          if (!header.jwk) throw new Error('DPoP proof must contain jwk in header');
+          return jose.importJWK(header.jwk);
+        },
+        {
+          typ: 'dpop+jwt',
+          maxTokenAge: '300s',
+        },
+      );
+
+      if (payload.htm !== request.method) {
+        throw new Error('DPoP htm does not match request method');
+      }
+
+      const expectedUri = `${request.protocol}://${request.hostname}${request.url.split('?')[0]}`;
+      if (payload.htu !== expectedUri) {
+        throw new Error('DPoP htu does not match request URI');
+      }
+
+      return true;
+    } catch (error) {
+      this.logger.warn(
+        `DPoP validation failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      throw new UnauthorizedException('Invalid DPoP proof');
+    }
+  }
+}

package/templates/recipes/dpop/tests/unit/shared/guards/dpop.guard.spec.ts

@@ -0,0 +1,69 @@
+import { ExecutionContext, UnauthorizedException } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { Test } from '@nestjs/testing';
+import { DPoPGuard } from '@/shared/guards/dpop.guard';
+
+describe('DPoPGuard', () => {
+  let guard: DPoPGuard;
+
+  const mockConfigService = {
+    getOrThrow: jest.fn(),
+  };
+
+  function createMockContext(headers: Record<string, string | undefined>): ExecutionContext {
+    return {
+      switchToHttp: () => ({
+        getRequest: () => ({
+          headers,
+          method: 'GET',
+          protocol: 'https',
+          hostname: 'api.example.com',
+          url: '/resource?page=1',
+        }),
+      }),
+    } as unknown as ExecutionContext;
+  }
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [DPoPGuard, { provide: ConfigService, useValue: mockConfigService }],
+    }).compile();
+
+    guard = module.get(DPoPGuard);
+  });
+
+  it('should be defined', () => {
+    expect(guard).toBeDefined();
+  });
+
+  it('should throw UnauthorizedException when DPoP header is missing', async () => {
+    const context = createMockContext({
+      authorization: 'DPoP some-token',
+    });
+
+    await expect(guard.canActivate(context)).rejects.toThrow(UnauthorizedException);
+    await expect(guard.canActivate(context)).rejects.toThrow('Missing DPoP proof header');
+  });
+
+  it('should throw UnauthorizedException when Authorization header does not use DPoP scheme', async () => {
+    const context = createMockContext({
+      dpop: 'some-proof-jwt',
+      authorization: 'Bearer some-token',
+    });
+
+    await expect(guard.canActivate(context)).rejects.toThrow(UnauthorizedException);
+    await expect(guard.canActivate(context)).rejects.toThrow(
+      'Authorization header must use DPoP scheme',
+    );
+  });
+
+  it('should throw UnauthorizedException for an invalid DPoP proof JWT', async () => {
+    const context = createMockContext({
+      dpop: 'invalid.jwt.token',
+      authorization: 'DPoP some-token',
+    });
+
+    await expect(guard.canActivate(context)).rejects.toThrow(UnauthorizedException);
+    await expect(guard.canActivate(context)).rejects.toThrow('Invalid DPoP proof');
+  });
+});

package/templates/recipes/drizzle-postgres/README.md

@@ -0,0 +1,68 @@
+# Drizzle ORM + PostgreSQL
+
+Lightweight type-safe ORM with best-in-class performance.
+
+## Links
+
+- [Drizzle ORM Documentation](https://orm.drizzle.team/docs/overview)
+- [Get Started with PostgreSQL](https://orm.drizzle.team/docs/get-started/postgresql-new)
+- [drizzle-orm on npm](https://www.npmjs.com/package/drizzle-orm)
+
+## Dependencies
+
+| Package       | Version | Type |
+| ------------- | ------- | ---- |
+| `drizzle-orm` | 0.44.2  | prod |
+| `pg`          | 8.13.1  | prod |
+| `drizzle-kit` | 0.31.1  | dev  |
+
+## Environment Variables
+
+| Variable       | Default                                           | Description               |
+| -------------- | ------------------------------------------------- | ------------------------- |
+| `DATABASE_URL` | `postgres://postgres:postgres@localhost:5432/app` | PostgreSQL connection URL |
+
+## Package.json Scripts
+
+Add these scripts to your `package.json`:
+
+```json
+{
+  "drizzle:generate": "drizzle-kit generate",
+  "drizzle:migrate": "drizzle-kit migrate",
+  "drizzle:studio": "drizzle-kit studio"
+}
+```
+
+## Usage
+
+Import the `DrizzleModule` in your `AppModule`. Then inject the database connection using the `DRIZZLE` token:
+
+```typescript
+import { Inject, Injectable } from '@nestjs/common';
+import { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { DRIZZLE } from '@/infrastructure/database/drizzle.module';
+import * as schema from '@/infrastructure/database/schema';
+
+@Injectable()
+export class UserRepository {
+  constructor(@Inject(DRIZZLE) private readonly db: NodePgDatabase<typeof schema>) {}
+
+  async findAll() {
+    return this.db.select().from(schema.users);
+  }
+}
+```
+
+## Schema
+
+Define tables in `src/infrastructure/database/schema/` and export them from the `index.ts` barrel file. See `example.ts` for a reference.
+
+## Migrations
+
+After changing schema files:
+
+1. Generate migration: `pnpm drizzle:generate`
+2. Apply migration: `pnpm drizzle:migrate`
+
+Use `pnpm drizzle:studio` to browse your database visually.

package/templates/recipes/drizzle-postgres/drizzle.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'drizzle-kit';
+
+export default defineConfig({
+  dialect: 'postgresql',
+  schema: './src/infrastructure/database/schema/*',
+  out: './drizzle',
+  dbCredentials: {
+    url: process.env.DATABASE_URL ?? (() => { throw new Error('DATABASE_URL environment variable is required'); })(),
+  },
+});

package/templates/recipes/drizzle-postgres/src/infrastructure/database/drizzle.module.ts

@@ -0,0 +1,25 @@
+import { Module, Global } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { drizzle, NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { Pool } from 'pg';
+import * as schema from './schema/index';
+
+export const DRIZZLE = Symbol('DRIZZLE');
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: DRIZZLE,
+      inject: [ConfigService],
+      useFactory: (configService: ConfigService) => {
+        const pool = new Pool({
+          connectionString: configService.getOrThrow<string>('DATABASE_URL'),
+        });
+        return drizzle(pool, { schema });
+      },
+    },
+  ],
+  exports: [DRIZZLE],
+})
+export class DrizzleModule {}

package/templates/recipes/drizzle-postgres/src/infrastructure/database/schema/example.ts

@@ -0,0 +1,9 @@
+import { pgTable, uuid, varchar, timestamp } from 'drizzle-orm/pg-core';
+
+export const users = pgTable('users', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  email: varchar('email', { length: 255 }).notNull().unique(),
+  name: varchar('name', { length: 255 }).notNull(),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+});

package/templates/recipes/drizzle-postgres/src/infrastructure/database/schema/index.ts

@@ -0,0 +1,3 @@
+// Export all schema definitions here
+// Example:
+// export { users } from './users';

package/templates/recipes/drizzle-postgres/tests/unit/infrastructure/database/drizzle.module.spec.ts

@@ -0,0 +1,35 @@
+import { Test } from '@nestjs/testing';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+
+const DRIZZLE = Symbol('DRIZZLE');
+
+describe('DrizzleModule', () => {
+  it('should provide the DRIZZLE token via the module', async () => {
+    const mockDb = { query: jest.fn() };
+
+    const module = await Test.createTestingModule({
+      imports: [ConfigModule.forRoot({ isGlobal: true })],
+      providers: [
+        {
+          provide: DRIZZLE,
+          useValue: mockDb,
+        },
+      ],
+    }).compile();
+
+    const db = module.get(DRIZZLE);
+    expect(db).toBeDefined();
+    expect(db).toBe(mockDb);
+  });
+
+  it('should use DATABASE_URL from ConfigService in the factory', () => {
+    const configService = new ConfigService({ DATABASE_URL: 'postgresql://localhost:5432/test' });
+    const url = configService.getOrThrow<string>('DATABASE_URL');
+    expect(url).toBe('postgresql://localhost:5432/test');
+  });
+
+  it('should throw when DATABASE_URL is missing', () => {
+    const configService = new ConfigService({});
+    expect(() => configService.getOrThrow('DATABASE_URL')).toThrow();
+  });
+});

package/templates/recipes/env-per-environment/.env.development

@@ -0,0 +1,17 @@
+# Development Environment
+NODE_ENV=development
+PORT=3000
+
+# Database
+DATABASE_HOST=localhost
+DATABASE_PORT=5432
+DATABASE_USER=postgres
+DATABASE_PASSWORD=postgres
+DATABASE_NAME=app_dev
+
+# Redis
+REDIS_HOST=localhost
+REDIS_PORT=6379
+
+# Logging
+LOG_LEVEL=debug

package/templates/recipes/env-per-environment/.env.production

@@ -0,0 +1,20 @@
+# Production Environment
+# All values must be provided via deployment configuration.
+# Do NOT commit actual secrets to version control.
+
+NODE_ENV=production
+PORT=3000
+
+# Database
+DATABASE_HOST=
+DATABASE_PORT=5432
+DATABASE_USER=
+DATABASE_PASSWORD=
+DATABASE_NAME=
+
+# Redis
+REDIS_HOST=
+REDIS_PORT=6379
+
+# Logging
+LOG_LEVEL=info

package/templates/recipes/env-per-environment/.env.test

@@ -0,0 +1,17 @@
+# Test Environment
+NODE_ENV=test
+PORT=3001
+
+# Database
+DATABASE_HOST=localhost
+DATABASE_PORT=5432
+DATABASE_USER=postgres
+DATABASE_PASSWORD=postgres
+DATABASE_NAME=app_test
+
+# Redis
+REDIS_HOST=localhost
+REDIS_PORT=6379
+
+# Logging
+LOG_LEVEL=warn

package/templates/recipes/env-per-environment/README.md

@@ -0,0 +1,40 @@
+# Per-Environment Configuration
+
+Environment-specific `.env` files for development, test, and production.
+
+## Links
+
+- [NestJS Configuration](https://docs.nestjs.com/techniques/configuration)
+- [dotenv on npm](https://www.npmjs.com/package/dotenv)
+
+## Dependencies
+
+| Package          | Version | Purpose                          |
+| ---------------- | ------- | -------------------------------- |
+| `@nestjs/config` | `4.0.2` | Environment configuration module |
+
+## Usage
+
+Load the correct env file based on `NODE_ENV` in your `AppModule`:
+
+```typescript
+import { ConfigModule } from '@nestjs/config';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      envFilePath: [`.env.${process.env.NODE_ENV || 'development'}`, '.env'],
+      isGlobal: true,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Generated Files
+
+| File               | Description                         |
+| ------------------ | ----------------------------------- |
+| `.env.development` | Development environment defaults    |
+| `.env.test`        | Test environment defaults           |
+| `.env.production`  | Production environment placeholders |

package/templates/recipes/feature-flags/README.md

@@ -0,0 +1,45 @@
+# Feature Flags
+
+Config-based feature flag service for toggling features at runtime.
+
+## Links
+
+- [NestJS Configuration](https://docs.nestjs.com/techniques/configuration)
+
+## Dependencies
+
+No additional dependencies required. Uses the built-in NestJS ConfigService.
+
+| Package | Version | Purpose                   |
+| ------- | ------- | ------------------------- |
+| (none)  | -       | Built-in `@nestjs/config` |
+
+## Environment Variables
+
+Feature flags are defined as environment variables with the `FF_` prefix:
+
+| Variable           | Description               | Example |
+| ------------------ | ------------------------- | ------- |
+| `FF_NEW_DASHBOARD` | Enable new dashboard UI   | `true`  |
+| `FF_BETA_API`      | Enable beta API endpoints | `false` |
+
+## Usage
+
+```typescript
+import { FeatureFlagService } from '@/shared/services/feature-flag.service';
+
+constructor(private readonly flags: FeatureFlagService) {}
+
+if (this.flags.isEnabled('NEW_DASHBOARD')) {
+  // new dashboard logic
+}
+
+// With default value
+const limit = this.flags.getValue('RATE_LIMIT', '100');
+```
+
+## Generated Files
+
+| File                                          | Description                       |
+| --------------------------------------------- | --------------------------------- |
+| `src/shared/services/feature-flag.service.ts` | Config-based feature flag service |

package/templates/recipes/feature-flags/src/shared/services/feature-flag.service.ts

@@ -0,0 +1,48 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+
+@Injectable()
+export class FeatureFlagService {
+  private readonly logger = new Logger(FeatureFlagService.name);
+  private readonly prefix = 'FF_';
+
+  constructor(private readonly config: ConfigService) {}
+
+  isEnabled(flagName: string): boolean {
+    const key = this.resolveKey(flagName);
+    const value = this.config.get<string>(key);
+
+    if (value === undefined) {
+      this.logger.debug(`Feature flag "${flagName}" not configured, defaulting to disabled`);
+      return false;
+    }
+
+    return value === 'true' || value === '1';
+  }
+
+  isDisabled(flagName: string): boolean {
+    return !this.isEnabled(flagName);
+  }
+
+  getValue<T extends string = string>(flagName: string, defaultValue: T): T {
+    const key = this.resolveKey(flagName);
+    return this.config.get<T>(key, defaultValue);
+  }
+
+  getAllFlags(): Record<string, string> {
+    const flags: Record<string, string> = {};
+
+    for (const [key, value] of Object.entries(process.env)) {
+      if (key.startsWith(this.prefix) && value !== undefined) {
+        const flagName = key.slice(this.prefix.length);
+        flags[flagName] = value;
+      }
+    }
+
+    return flags;
+  }
+
+  private resolveKey(flagName: string): string {
+    return flagName.startsWith(this.prefix) ? flagName : `${this.prefix}${flagName}`;
+  }
+}