spoonfeeder 0.1.0

package/templates/recipes/ai-context/cursor/auth.mdc

@@ -0,0 +1,44 @@
+---
+description: Authentication and authorization patterns
+globs: ["**/*.guard.ts", "**/*.strategy.ts", "**/*.controller.ts", "**/auth/**"]
+---
+
+# Auth Rules
+
+## Route Protection
+- All routes are protected by default via a global `JwtAuthGuard`
+- Use `@Public()` decorator to mark routes that skip authentication
+- Never disable the global guard — use `@Public()` for open endpoints
+
+```ts
+@Public()
+@Post('login')
+login(@Body() dto: LoginDto) { ... }
+```
+
+## User Extraction
+- Use `@CurrentUser()` parameter decorator to get the authenticated user
+- Never read from `request.user` directly in controllers
+
+```ts
+@Get('profile')
+getProfile(@CurrentUser() user: JwtPayload) {
+  return this.userService.findById(user.sub);
+}
+```
+
+## JWT Flow
+- Access tokens are short-lived (15 minutes default)
+- Refresh tokens are long-lived and stored securely
+- The `/auth/refresh` endpoint issues a new access token from a valid refresh token
+- Revoke refresh tokens on password change or logout
+
+## Authorization
+- Use custom guards for role-based or permission-based access
+- Place authorization guards after authentication: `@UseGuards(JwtAuthGuard, RolesGuard)`
+- Use `@Roles()` decorator to declare required roles on handlers
+
+## Passwords
+- Hash passwords with bcrypt (minimum 10 rounds)
+- Never log or return password fields
+- Exclude password from entity serialization using `class-transformer` `@Exclude()`

package/templates/recipes/ai-context/cursor/base.mdc

@@ -0,0 +1,44 @@
+---
+description: Base rules for NestJS projects generated by spoonfeeder
+globs: ["**/*.ts"]
+---
+
+# NestJS Project Rules
+
+## Imports
+- Always use the `@/*` path alias for internal imports (maps to `src/*`)
+- Never use relative paths like `../../`
+
+## Architecture
+- Follow 3-layer architecture: Controller -> Service -> Repository/Data Access
+- Controllers handle HTTP concerns only — no business logic
+- Services contain business logic — max 200 lines per file
+- No private methods in services — extract to separate injectable classes
+
+## Services
+- One class per file, one responsibility per class
+- Use descriptive file suffixes: `.service.ts`, `.processor.ts`, `.importer.ts`, `.scheduler.ts`
+- Class names match file purpose: `FileImporter` not `FileImporterService`
+- Inject dependencies via constructor
+
+## DTOs
+- Use `class-validator` decorators for all request DTOs
+- Use `class-transformer` for response serialization
+- Place DTOs in a `dto/` subdirectory within each feature module
+
+## Modules
+- Organize by feature domain, not by technical layer
+- Each feature gets its own module, controller, and service
+- Export only what other modules need
+
+## Error Handling
+- Use NestJS built-in exceptions (`NotFoundException`, `BadRequestException`, etc.)
+- Never catch exceptions just to rethrow them
+- Let the global exception filter handle unexpected errors
+
+## Testing
+- Mock only external dependencies (databases, HTTP clients, third-party SDKs)
+- Never mock code you own
+- Tests live in `tests/` at the project root, mirroring `src/` structure
+- Unit tests: `tests/unit/` with `.spec.ts` suffix
+- Integration tests: `tests/integration/` with `.integration.spec.ts` suffix

package/templates/recipes/ai-context/cursor/prisma.mdc

@@ -0,0 +1,43 @@
+---
+description: Prisma patterns and conventions
+globs: ["**/prisma/**", "**/*.prisma", "**/*.repository.ts", "**/*.service.ts"]
+---
+
+# Prisma Rules
+
+## Schema Design
+- Define models in `prisma/schema.prisma`
+- Use `@id @default(uuid())` for primary keys
+- Use `@map()` and `@@map()` to control database table/column names
+- Add `createdAt` and `updatedAt` fields to all models
+- Define explicit relation names when a model has multiple relations to the same table
+
+```prisma
+model User {
+  id        String   @id @default(uuid())
+  email     String   @unique
+  name      String
+  posts     Post[]
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  @@map("users")
+}
+```
+
+## Client Usage
+- Inject `PrismaService` (extends `PrismaClient`) via NestJS DI
+- Never instantiate `PrismaClient` directly in application code
+- Use `select` or `include` explicitly — avoid fetching unnecessary relations
+- Use transactions (`prisma.$transaction()`) for multi-step writes
+
+## Migrations
+- Run `pnpm prisma migrate dev --name <kebab-case-name>` during development
+- Run `pnpm prisma migrate deploy` in CI/production
+- Never edit generated migration SQL after it has been applied
+- Always run `pnpm prisma generate` after schema changes
+
+## Error Handling
+- Catch `PrismaClientKnownRequestError` for constraint violations
+- Use error codes: `P2002` (unique), `P2025` (not found), `P2003` (foreign key)
+- Map Prisma errors to NestJS exceptions in the service layer

package/templates/recipes/ai-context/cursor/swagger.mdc

@@ -0,0 +1,48 @@
+---
+description: Swagger/OpenAPI conventions
+globs: ["**/*.controller.ts", "**/*.dto.ts"]
+---
+
+# Swagger Rules
+
+## DTOs
+- Add `@ApiProperty()` to every property in request and response DTOs
+- Include `description`, `example`, and `type` in `@ApiProperty()` when not obvious
+- Use `@ApiPropertyOptional()` for optional fields
+- Mark enums with `{ enum: MyEnum }` in the decorator
+
+```ts
+export class CreateUserDto {
+  @ApiProperty({ description: 'User email address', example: 'user@example.com' })
+  @IsEmail()
+  email: string;
+
+  @ApiPropertyOptional({ description: 'Display name', example: 'Jane Doe' })
+  @IsString()
+  @IsOptional()
+  name?: string;
+}
+```
+
+## Controllers
+- Add `@ApiTags('<resource>')` at the class level to group endpoints
+- Add `@ApiOperation({ summary: '...' })` to every handler method
+- Use `@ApiResponse()` for non-2xx responses (400, 401, 404, etc.)
+- Use `@ApiParam()` for path parameters and `@ApiQuery()` for query parameters
+
+```ts
+@ApiTags('users')
+@Controller('users')
+export class UserController {
+  @Get(':id')
+  @ApiOperation({ summary: 'Get user by ID' })
+  @ApiParam({ name: 'id', type: String })
+  @ApiResponse({ status: 404, description: 'User not found' })
+  findOne(@Param('id') id: string) { ... }
+}
+```
+
+## General
+- Do not use `@ApiExcludeEndpoint()` unless the route is truly internal
+- Keep operation summaries short (under 60 characters)
+- Use consistent naming: plural nouns for resource tags (e.g. `users`, `invoices`)

package/templates/recipes/ai-context/cursor/testing.mdc

@@ -0,0 +1,58 @@
+---
+description: Testing patterns and conventions
+globs: ["**/*.spec.ts", "**/*.e2e-spec.ts", "tests/**"]
+---
+
+# Testing Rules
+
+## File Naming and Location
+- Tests live in `tests/` at the project root, mirroring `src/` structure
+- Unit tests: `tests/unit/<path>/<name>.spec.ts`
+- Integration tests: `tests/integration/<path>/<name>.integration.spec.ts`
+- E2E tests: `tests/e2e/<name>.e2e-spec.ts`
+- Test factories: `tests/factories/<name>.factory.ts`
+
+## Unit Tests
+- Test every public method — happy path, edge cases, error paths
+- Mock only external dependencies (database, HTTP, third-party SDKs)
+- Never mock code you own — use real instances
+- Use `Test.createTestingModule()` from `@nestjs/testing`
+
+```ts
+const module = await Test.createTestingModule({
+  providers: [
+    UserService,
+    { provide: UserRepository, useValue: mockRepository },
+  ],
+}).compile();
+```
+
+## Integration Tests
+- Use Testcontainers to spin up real databases
+- Test the full NestJS module with real providers
+- Focus on data persistence and cross-service interactions
+- Clean up test data between tests
+
+## E2E Tests
+- Test the HTTP boundary only — use `supertest` against the running app
+- Verify status codes, response shapes, and headers
+- Do not test internal implementation details
+
+## Factories
+- Create test data builders in `tests/factories/`
+- Use the builder pattern with sensible defaults
+- Override only the fields relevant to each test
+
+```ts
+export const createUserFixture = (overrides?: Partial<User>): User => ({
+  id: randomUUID(),
+  email: 'test@example.com',
+  name: 'Test User',
+  ...overrides,
+});
+```
+
+## General
+- Avoid `any` in test code — use proper types
+- One `describe` block per method, nested `it` blocks per scenario
+- Clean up side effects (files, database rows) in `afterEach` or `afterAll`

package/templates/recipes/ai-context/cursor/typeorm.mdc

@@ -0,0 +1,49 @@
+---
+description: TypeORM patterns and conventions
+globs: ["**/*.entity.ts", "**/*.repository.ts", "**/migrations/**"]
+---
+
+# TypeORM Rules
+
+## Entities
+- One entity per file, suffix `.entity.ts`
+- Use `@Entity()` with an explicit table name: `@Entity('users')`
+- Always define a primary key with `@PrimaryGeneratedColumn('uuid')`
+- Use `@Column()` with explicit types for non-string columns
+- Add `@CreateDateColumn()` and `@UpdateDateColumn()` to all entities
+- Define relations with explicit join columns and cascade options
+
+```ts
+@Entity('users')
+export class UserEntity {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ type: 'varchar', length: 255 })
+  email: string;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @UpdateDateColumn()
+  updatedAt: Date;
+}
+```
+
+## Repositories
+- Use the repository pattern via `@InjectRepository()`
+- Never call `getRepository()` or `getManager()` directly
+- Create custom repository methods for complex queries
+- Use QueryBuilder for queries involving joins or conditions beyond simple `find`
+
+## Migrations
+- Never modify an applied migration — create a new one
+- Implement both `up()` and `down()` methods
+- Use `migration:generate` to auto-generate from entity changes
+- Test both directions locally before committing
+
+## Queries
+- Use parameterized queries — never interpolate user input into SQL
+- Prefer `findOne({ where: { ... } })` over `findOneBy()` for clarity
+- Use `select` to limit returned columns in performance-sensitive queries
+- Add `@Index()` decorators for frequently queried columns

package/templates/recipes/api-keys/README.md

@@ -0,0 +1,44 @@
+# API Key Authentication
+
+Custom API key authentication using the `x-api-key` header for NestJS applications.
+
+## Links
+
+- [NestJS Guards Documentation](https://docs.nestjs.com/guards)
+- [NestJS Security Documentation](https://docs.nestjs.com/security/authentication)
+
+## Dependencies
+
+| Package          | Version   | Purpose                                                      |
+| ---------------- | --------- | ------------------------------------------------------------ |
+| `@nestjs/common` | `10.4.15` | Core NestJS decorators and guards (included in base)         |
+| `@nestjs/config` | `3.3.0`   | Configuration module for reading API keys (included in base) |
+
+## Environment Variables
+
+| Variable  | Default | Description                                                |
+| --------- | ------- | ---------------------------------------------------------- |
+| `API_KEY` | —       | The API key clients must provide in the `x-api-key` header |
+
+## Usage
+
+```typescript
+// Protect a route with API key authentication
+@Controller('webhooks')
+export class WebhookController {
+  @UseGuards(ApiKeyGuard)
+  @Post('stripe')
+  handleStripeWebhook(@Body() payload: any) {
+    return { received: true };
+  }
+}
+
+// Or apply globally in main.ts
+app.useGlobalGuards(app.get(ApiKeyGuard));
+```
+
+## Generated Files
+
+| File                                 | Description                                                            |
+| ------------------------------------ | ---------------------------------------------------------------------- |
+| `src/shared/guards/api-key.guard.ts` | Guard that validates the `x-api-key` header against configured API key |

package/templates/recipes/api-keys/src/shared/guards/api-key.guard.ts

@@ -0,0 +1,32 @@
+import { CanActivate, ExecutionContext, Injectable, UnauthorizedException } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { FastifyRequest } from 'fastify';
+import { timingSafeEqual } from 'node:crypto';
+
+@Injectable()
+export class ApiKeyGuard implements CanActivate {
+  constructor(private readonly configService: ConfigService) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const request = context.switchToHttp().getRequest<FastifyRequest>();
+    const apiKey = request.headers['x-api-key'] as string;
+    const validApiKey = this.configService.get<string>('API_KEY');
+
+    if (!apiKey || !validApiKey) {
+      throw new UnauthorizedException('API key is required');
+    }
+
+    if (!this.isEqual(apiKey, validApiKey)) {
+      throw new UnauthorizedException('Invalid API key');
+    }
+
+    return true;
+  }
+
+  private isEqual(a: string, b: string): boolean {
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    if (bufA.length !== bufB.length) return false;
+    return timingSafeEqual(bufA, bufB);
+  }
+}

package/templates/recipes/api-keys/tests/unit/shared/guards/api-key.guard.spec.ts

@@ -0,0 +1,40 @@
+import { ExecutionContext, UnauthorizedException } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { ApiKeyGuard } from '../../../../src/shared/guards/api-key.guard';
+
+describe('ApiKeyGuard', () => {
+  let guard: ApiKeyGuard;
+  let configService: ConfigService;
+
+  const createMockContext = (apiKey?: string): ExecutionContext =>
+    ({
+      switchToHttp: () => ({
+        getRequest: () => ({
+          headers: apiKey !== undefined ? { 'x-api-key': apiKey } : {},
+        }),
+      }),
+    }) as unknown as ExecutionContext;
+
+  beforeEach(() => {
+    configService = { get: jest.fn().mockReturnValue('valid-key') } as unknown as ConfigService;
+    guard = new ApiKeyGuard(configService);
+  });
+
+  it('should throw UnauthorizedException when x-api-key header is missing', () => {
+    const context = createMockContext();
+
+    expect(() => guard.canActivate(context)).toThrow(UnauthorizedException);
+  });
+
+  it('should throw UnauthorizedException when api key does not match', () => {
+    const context = createMockContext('wrong-key');
+
+    expect(() => guard.canActivate(context)).toThrow(UnauthorizedException);
+  });
+
+  it('should return true when api key is valid', () => {
+    const context = createMockContext('valid-key');
+
+    expect(guard.canActivate(context)).toBe(true);
+  });
+});

package/templates/recipes/api-versioning/README.md

@@ -0,0 +1,63 @@
+# API Versioning
+
+URI-based API versioning for NestJS.
+
+## Links
+
+- [NestJS Versioning](https://docs.nestjs.com/techniques/versioning)
+
+## Dependencies
+
+No additional dependencies required. Versioning is built into NestJS core.
+
+| Package | Version | Purpose                    |
+| ------- | ------- | -------------------------- |
+| (none)  | -       | Built-in to `@nestjs/core` |
+
+## Usage
+
+Enable versioning in `main.ts`:
+
+```typescript
+import { VersioningType } from '@nestjs/common';
+
+app.enableVersioning({
+  type: VersioningType.URI,
+  defaultVersion: '1',
+  prefix: 'v',
+});
+```
+
+Use version-specific controllers:
+
+```typescript
+@Controller({ path: 'users', version: '1' })
+export class UsersV1Controller {
+  @Get()
+  findAll() {
+    return [];
+  }
+}
+
+@Controller({ path: 'users', version: '2' })
+export class UsersV2Controller {
+  @Get()
+  findAll() {
+    return { items: [], total: 0 };
+  }
+}
+```
+
+Or version individual routes:
+
+```typescript
+@Version('2')
+@Get()
+findAllV2() { return { items: [], total: 0 }; }
+```
+
+## Generated Files
+
+| File   | Description                                 |
+| ------ | ------------------------------------------- |
+| (none) | Applied directly in `main.ts` configuration |

package/templates/recipes/audit-trail/README.md

@@ -0,0 +1,75 @@
+# Audit Trail
+
+Record entity changes with user, action, and diff for compliance and debugging.
+
+## Links
+
+- [NestJS Interceptors](https://docs.nestjs.com/interceptors)
+- [TypeORM Subscribers](https://typeorm.io/listeners-and-subscribers#what-is-a-subscriber)
+
+## Dependencies
+
+None — uses NestJS interceptors and decorators.
+
+## Usage
+
+### Interceptor Approach
+
+Apply `AuditInterceptor` globally or per-controller to log mutating requests:
+
+```typescript
+import { AuditInterceptor } from '@/shared/interceptors/audit.interceptor';
+
+@Module({
+  providers: [
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: AuditInterceptor,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+Or apply per-controller:
+
+```typescript
+@UseInterceptors(AuditInterceptor)
+@Controller('users')
+export class UsersController {}
+```
+
+Use the `@Auditable()` decorator to mark controllers or handlers for selective auditing:
+
+```typescript
+@Auditable()
+@Controller('orders')
+export class OrdersController {}
+```
+
+### TypeORM Subscriber Approach
+
+For entity-level auditing, use a TypeORM subscriber:
+
+```typescript
+@EventSubscriber()
+export class AuditSubscriber implements EntitySubscriberInterface {
+  afterUpdate(event: UpdateEvent<any>): void {
+    // Log old vs new values from event.databaseEntity and event.entity
+  }
+}
+```
+
+### Compliance Use Cases
+
+- **GDPR**: Track who accessed or modified personal data
+- **SOC 2**: Maintain change logs for audit controls
+- **HIPAA**: Record access to protected health information
+- **Financial**: Immutable trail for transaction modifications
+
+## Generated Files
+
+| File                                           | Description                                             |
+| ---------------------------------------------- | ------------------------------------------------------- |
+| `src/shared/interceptors/audit.interceptor.ts` | Interceptor that records mutating request audit entries |
+| `src/shared/decorators/auditable.decorator.ts` | Metadata decorator to mark auditable controllers        |

package/templates/recipes/audit-trail/src/shared/decorators/auditable.decorator.ts

@@ -0,0 +1,4 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const AUDITABLE_KEY = 'AUDITABLE';
+export const Auditable = () => SetMetadata(AUDITABLE_KEY, true);

package/templates/recipes/audit-trail/src/shared/interceptors/audit.interceptor.ts

@@ -0,0 +1,46 @@
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { tap } from 'rxjs/operators';
+import { FastifyRequest } from 'fastify';
+
+export interface AuditEntry {
+  userId: string | null;
+  action: string;
+  entityName: string;
+  entityId: string;
+  changes: Record<string, { from: unknown; to: unknown }>;
+  timestamp: Date;
+  ip: string;
+}
+
+@Injectable()
+export class AuditInterceptor implements NestInterceptor {
+  // TODO: Replace this in-memory store with a persistent backend (database, message queue).
+  // This implementation is for development only — entries are lost on restart and unbounded in memory.
+  private readonly entries: AuditEntry[] = [];
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const request = context.switchToHttp().getRequest<FastifyRequest>();
+    const method = request.method;
+
+    return next.handle().pipe(
+      tap((response) => {
+        if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+          this.entries.push({
+            userId: (request as any).user?.sub ?? null,
+            action: method,
+            entityName: context.getClass().name,
+            entityId: (request.params as any)?.id ?? 'unknown',
+            changes: {},
+            timestamp: new Date(),
+            ip: request.ip,
+          });
+        }
+      }),
+    );
+  }
+
+  getEntries(): AuditEntry[] {
+    return [...this.entries];
+  }
+}

package/templates/recipes/audit-trail/tests/unit/shared/interceptors/audit.interceptor.spec.ts

@@ -0,0 +1,82 @@
+import {
+  AuditInterceptor,
+  AuditEntry,
+} from '../../../../src/shared/interceptors/audit.interceptor';
+import { ExecutionContext, CallHandler } from '@nestjs/common';
+import { of } from 'rxjs';
+
+function createMockExecutionContext(overrides: {
+  method: string;
+  params?: Record<string, string>;
+  user?: { sub: string };
+  ip?: string;
+  className?: string;
+}): ExecutionContext {
+  return {
+    switchToHttp: () => ({
+      getRequest: () => ({
+        method: overrides.method,
+        params: overrides.params ?? {},
+        user: overrides.user,
+        ip: overrides.ip ?? '127.0.0.1',
+      }),
+    }),
+    getClass: () => ({ name: overrides.className ?? 'TestController' }),
+  } as unknown as ExecutionContext;
+}
+
+function createMockCallHandler(response: unknown = {}): CallHandler {
+  return { handle: () => of(response) };
+}
+
+describe('AuditInterceptor', () => {
+  let interceptor: AuditInterceptor;
+
+  beforeEach(() => {
+    interceptor = new AuditInterceptor();
+  });
+
+  it('should capture an audit entry for a POST request', (done) => {
+    const context = createMockExecutionContext({
+      method: 'POST',
+      params: { id: '42' },
+      user: { sub: 'user-1' },
+    });
+
+    interceptor.intercept(context, createMockCallHandler()).subscribe(() => {
+      const entries = interceptor.getEntries();
+
+      expect(entries).toHaveLength(1);
+      expect(entries[0]).toEqual(
+        expect.objectContaining({
+          action: 'POST',
+          entityId: '42',
+          userId: 'user-1',
+          entityName: 'TestController',
+        }),
+      );
+      done();
+    });
+  });
+
+  it('should not capture an entry for a GET request', (done) => {
+    const context = createMockExecutionContext({ method: 'GET' });
+
+    interceptor.intercept(context, createMockCallHandler()).subscribe(() => {
+      expect(interceptor.getEntries()).toHaveLength(0);
+      done();
+    });
+  });
+
+  it('should default userId to null when no user is present', (done) => {
+    const context = createMockExecutionContext({ method: 'DELETE' });
+
+    interceptor.intercept(context, createMockCallHandler()).subscribe(() => {
+      const entries = interceptor.getEntries();
+
+      expect(entries).toHaveLength(1);
+      expect(entries[0].userId).toBeNull();
+      done();
+    });
+  });
+});