spoonfeeder 0.1.0

package/templates/recipes/adminjs/README.md

@@ -0,0 +1,145 @@
+# AdminJS — Auto-Generated CRUD Admin Panel
+
+An out-of-the-box admin panel powered by [AdminJS](https://adminjs.co/) that provides auto-generated CRUD interfaces for your entities.
+
+## Links
+
+- [AdminJS Website](https://adminjs.co/)
+- [NestJS Plugin Docs](https://docs.adminjs.co/installation/plugins/nest-js)
+- [npm — adminjs](https://www.npmjs.com/package/adminjs)
+
+## Dependencies
+
+| Package                    | Version  |
+| -------------------------- | -------- |
+| `adminjs`                  | 7.8.13   |
+| `@adminjs/nestjs`          | 6.1.0    |
+| `@adminjs/express`         | 6.1.0    |
+| `@nestjs/platform-express` | 11.1.19  |
+| `express-session`          | 1.18.1   |
+| `express-formidable`       | 1.2.0    |
+| `@types/express-session`   | 1.18.1   |
+
+> **Note:** AdminJS requires the Express HTTP adapter (`@nestjs/platform-express`). The `@adminjs/nestjs` module uses `@adminjs/express` internally, which is incompatible with Fastify. The Express platform package is included automatically by this recipe.
+
+## Environment Variables
+
+| Variable         | Default             | Description                      |
+| ---------------- | ------------------- | -------------------------------- |
+| `ADMIN_EMAIL`    | `admin@example.com` | AdminJS login email              |
+| `ADMIN_PASSWORD` | _(empty)_           | AdminJS login password (required)|
+
+## Usage
+
+### Registering a TypeORM Entity as a Resource
+
+AdminJS uses ORM adapters to introspect your entities and generate CRUD interfaces automatically. Register the adapter once at startup, then add entities to the `resources` array in `AdminModule`.
+
+```typescript
+import AdminJS from 'adminjs';
+import { Resource, Database } from '@adminjs/typeorm';
+
+// Register the TypeORM adapter (do this once, e.g. in main.ts or admin.module.ts)
+AdminJS.registerAdapter({ Resource, Database });
+```
+
+Then add your entity to the resources array in `admin.module.ts`:
+
+```typescript
+resources: [
+  {
+    resource: UserEntity,
+    options: {
+      properties: {
+        password: { isVisible: false },
+      },
+    },
+  },
+],
+```
+
+### ORM Adapters
+
+AdminJS supports multiple ORM adapters. Install the one matching your database layer:
+
+| ORM       | Adapter Package      |
+| --------- | -------------------- |
+| TypeORM   | `@adminjs/typeorm`   |
+| Prisma    | `@adminjs/prisma`    |
+| Mongoose  | `@adminjs/mongoose`  |
+| MikroORM  | `@adminjs/mikroorm`  |
+| Sequelize | `@adminjs/sequelize` |
+
+Each adapter follows the same pattern: install the package, call `AdminJS.registerAdapter()`, and pass your entities/models as resources.
+
+## Generated Files
+
+| File                                    | Description                         |
+| --------------------------------------- | ----------------------------------- |
+| `src/app/modules/admin/admin.module.ts` | AdminJS module with auth and config |
+
+## Production Considerations
+
+- **Change the session secret**: Replace `'secret-session-key-change-in-production'` in `admin.module.ts` with a strong, randomly generated secret stored as an environment variable.
+- **Change admin credentials**: Set `ADMIN_EMAIL` and `ADMIN_PASSWORD` to strong values. Consider integrating with your existing authentication system instead of env-var-based credentials.
+- **Use a session store**: The default in-memory session store is not suitable for production. Use `connect-redis`, `connect-pg-simple`, or another persistent session store.
+
+## Customization
+
+### Custom Actions
+
+Add custom actions to any resource:
+
+```typescript
+resources: [
+  {
+    resource: OrderEntity,
+    options: {
+      actions: {
+        approve: {
+          actionType: 'record',
+          handler: async (request, response, context) => {
+            const { record } = context;
+            // custom approval logic
+            return { record: record.toJSON(), msg: 'Order approved' };
+          },
+        },
+      },
+    },
+  },
+],
+```
+
+### Custom Components
+
+Override default components with React-based custom components:
+
+```typescript
+const adminJsOptions = {
+  branding: {
+    companyName: 'My App',
+    logo: '/logo.png',
+  },
+  dashboard: {
+    component: AdminJS.bundle('./components/dashboard'),
+  },
+};
+```
+
+### Custom Dashboard
+
+Create a custom dashboard by providing a React component:
+
+```typescript
+// components/dashboard.tsx
+import React from 'react';
+import { Box, H2 } from '@adminjs/design-system';
+
+const Dashboard = () => (
+  <Box>
+    <H2>Welcome to the Admin Panel</H2>
+  </Box>
+);
+
+export default Dashboard;
+```

package/templates/recipes/adminjs/src/app/modules/admin/admin.module.ts

@@ -0,0 +1,59 @@
+import { Module } from '@nestjs/common';
+import { AdminModule as AdminJSModule } from '@adminjs/nestjs';
+import AdminJS from 'adminjs';
+
+@Module({
+  imports: [
+    AdminJSModule.createAdminAsync({
+      useFactory: () => ({
+        adminJsOptions: {
+          rootPath: '/admin',
+          branding: {
+            companyName: 'Admin Panel',
+            softwareBrothers: false,
+          },
+          resources: [
+            // Register your entities here:
+            // {
+            //   resource: UserEntity,
+            //   options: {
+            //     properties: {
+            //       password: { isVisible: false },
+            //     },
+            //   },
+            // },
+          ],
+        },
+        auth: {
+          authenticate: async (email: string, password: string) => {
+            const adminEmail = process.env.ADMIN_EMAIL;
+            const adminPassword = process.env.ADMIN_PASSWORD;
+            if (!adminEmail) throw new Error('ADMIN_EMAIL environment variable is required');
+            if (!adminPassword) throw new Error('ADMIN_PASSWORD environment variable is required');
+
+            if (email === adminEmail && password === adminPassword) {
+              return { email: adminEmail };
+            }
+            return null;
+          },
+          cookieName: 'adminjs',
+          cookiePassword: (() => {
+            const secret = process.env.ADMIN_SESSION_SECRET;
+            if (!secret) throw new Error('ADMIN_SESSION_SECRET environment variable is required');
+            return secret;
+          })(),
+        },
+        sessionOptions: {
+          resave: false,
+          saveUninitialized: false,
+          secret: (() => {
+            const secret = process.env.ADMIN_SESSION_SECRET;
+            if (!secret) throw new Error('ADMIN_SESSION_SECRET environment variable is required');
+            return secret;
+          })(),
+        },
+      }),
+    }),
+  ],
+})
+export class AdminModule {}

package/templates/recipes/adminjs/tests/unit/app/modules/admin/admin.module.spec.ts

@@ -0,0 +1,22 @@
+import { AdminModule } from '@/app/modules/admin/admin.module';
+
+describe('AdminModule', () => {
+  it('should be defined as a class', () => {
+    expect(AdminModule).toBeDefined();
+    expect(typeof AdminModule).toBe('function');
+  });
+
+  it('should be instantiable', () => {
+    const instance = new AdminModule();
+    expect(instance).toBeInstanceOf(AdminModule);
+  });
+
+  it('should have Module decorator metadata with imports', () => {
+    // Reflect.getMetadata is populated by @Module decorator at class-definition time.
+    // 'imports' is stored under the key 'imports' by NestJS.
+    const imports = Reflect.getMetadata('imports', AdminModule);
+    expect(imports).toBeDefined();
+    expect(Array.isArray(imports)).toBe(true);
+    expect(imports.length).toBeGreaterThan(0);
+  });
+});

package/templates/recipes/ai-context/README.md

@@ -0,0 +1,11 @@
+# AI Context
+
+Project context files for AI coding assistants. These files help AI tools understand the project structure, conventions, and patterns.
+
+## Providers
+
+| Provider              | Description                                                   |
+| --------------------- | ------------------------------------------------------------- |
+| [Claude](./claude/)   | `CLAUDE.md` project instructions and custom commands          |
+| [Cursor](./cursor/)   | `.cursor/rules/*.mdc` rule files for context-aware assistance |
+| [Copilot](./copilot/) | `.github/copilot-instructions.md` project guidance            |

package/templates/recipes/ai-context/claude/base.md

@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+## Package Manager
+
+Always use **pnpm**. Never use npm or yarn.
+
+## Imports
+
+Use the `@/*` alias for all internal imports — it maps to `src/*`.
+
+```ts
+// correct
+import { UserService } from '@/users/user.service';
+
+// wrong
+import { UserService } from '../../users/user.service';
+```
+
+## Code Style
+
+Formatting and linting are enforced automatically by lint-staged on commit. Do not run `pnpm lint` or `pnpm format` manually unless explicitly asked.
+
+Prettier config (`.prettierrc`): single quotes, semicolons, print width 100, tab width 2, trailing commas, LF line endings.
+
+## Branch Naming
+
+Format: `{type}/{TICKET_NUMBER}/{description}` or `{type}/{description}`
+
+- Allowed types: `feature` `fix` `hotfix` `release` `chore` `docs` `refactor` `test`
+- Description: lowercase, digits, hyphens only — no spaces or underscores
+- Ticket number: optional, uppercase letters + hyphen + digits (e.g. `PROJ-123`)
+- Exempt branches: `main`, `staging`, `production`
+
+Examples: `feature/PROJ-123/user-authentication`, `fix/token-refresh`, `chore/update-dependencies`
+
+## Commits
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/). commitlint enforces this on every commit.
+
+```
+<type>(<scope>): <description>
+```
+
+- **type**: `feat` `fix` `docs` `style` `refactor` `perf` `test` `build` `ci` `chore` `revert`
+- **scope**: optional, kebab-case (e.g. `auth`, `user-service`)
+- **description**: lowercase, imperative tense, no trailing period, max 100 characters
+
+Breaking changes: append `!` after type/scope and add a `BREAKING CHANGE:` footer.
+
+## Testing
+
+- Tests live in `tests/` at the project root, mirroring the `src/` structure
+- Unit tests: `tests/unit/` — one `.spec.ts` per source file
+- Integration tests: `tests/integration/` — uses Testcontainers, suffix `.integration.spec.ts`
+- E2E tests: `tests/e2e/` — HTTP boundary tests, suffix `.e2e-spec.ts`
+- Test factories: `tests/factories/` — shared test data builders
+- Unit test all service methods — happy path, edge cases, and error paths
+- **Mock only external dependencies** (databases, HTTP clients, third-party SDKs) — never mock code you own
+- Integration tests use a real NestJS testing module with real providers
+- Unit tests and type checking must pass before pushing (`pre-push` hook)
+
+## Key Commands
+
+| Command                 | Description                                |
+| ----------------------- | ------------------------------------------ |
+| `pnpm start:dev`        | Start with file watching                   |
+| `pnpm build`            | Compile to `dist/`                         |
+| `pnpm test`             | Run unit tests                             |
+| `pnpm test:unit`        | Run unit tests (explicit)                  |
+| `pnpm test:integration` | Run integration tests (Testcontainers)     |
+| `pnpm test:e2e`         | Run end-to-end tests                       |
+| `pnpm test:all`         | Run all test suites                        |
+| `pnpm test:cov`         | Run unit + integration tests with coverage |

package/templates/recipes/ai-context/claude/commands/add-command.md

@@ -0,0 +1,48 @@
+# Add CLI Command
+
+Scaffold a new CLI command using nest-commander.
+
+## Prompt
+
+Ask the user for:
+
+1. **Command name** (e.g. `sync-users`, `generate-report`)
+2. **Description** — short summary shown in `--help` output
+3. **Options/arguments** — any flags or positional arguments the command accepts
+
+## Steps
+
+1. **Create the command** at `src/commands/<command-name>.command.ts`:
+
+   ```ts
+   import { Command, CommandRunner, Option } from 'nest-commander';
+
+   @Command({
+     name: 'sync-users',
+     description: 'Synchronize users from external source',
+   })
+   export class SyncUsersCommand extends CommandRunner {
+     async run(passedParams: string[]): Promise<void> {
+       // command logic
+     }
+
+     @Option({
+       flags: '-d, --dry-run',
+       description: 'Preview changes without applying them',
+     })
+     parseDryRun(val: string): boolean {
+       return true;
+     }
+   }
+   ```
+
+2. **Extract business logic** — if the command does more than orchestration, create a dedicated service (e.g. `src/users/user-sync.service.ts`) and inject it into the command
+
+3. **Register in module** — add the command class to the `providers` array of the relevant module (usually `AppModule` or a feature module)
+
+4. **Create test stub** at `tests/unit/commands/<command-name>.command.spec.ts`:
+   - Use `TestingModule` from `@nestjs/testing`
+   - Test the `run()` method with different arguments and options
+   - Mock injected services
+
+5. **Verify** — run `pnpm build` and `pnpm test`

package/templates/recipes/ai-context/claude/commands/add-consumer.md

@@ -0,0 +1,58 @@
+# Add Message Consumer
+
+Scaffold a new message consumer for event-driven or RPC-style messaging.
+
+## Prompt
+
+Ask the user for:
+
+1. **Event or pattern name** (e.g. `order.created`, `user.sync`)
+2. **Pattern type**: `@EventPattern` (fire-and-forget) or `@MessagePattern` (request-reply)
+3. **Transport** if relevant (RabbitMQ, Kafka, Redis, NATS)
+
+## Steps
+
+1. **Create the handler** at `src/<domain>/<event-name>.handler.ts`:
+
+   For event patterns (fire-and-forget):
+
+   ```ts
+   import { Controller } from '@nestjs/common';
+   import { EventPattern, Payload } from '@nestjs/microservices';
+
+   @Controller()
+   export class OrderCreatedHandler {
+     @EventPattern('order.created')
+     async handle(@Payload() data: OrderCreatedEvent): Promise<void> {
+       // process event
+     }
+   }
+   ```
+
+   For message patterns (request-reply):
+
+   ```ts
+   import { Controller } from '@nestjs/common';
+   import { MessagePattern, Payload } from '@nestjs/microservices';
+
+   @Controller()
+   export class UserSyncHandler {
+     @MessagePattern('user.sync')
+     async handle(@Payload() data: UserSyncRequest): Promise<UserSyncResponse> {
+       // process and return response
+     }
+   }
+   ```
+
+2. **Create the event/message DTO** at `src/<domain>/dto/<event-name>.event.ts`:
+   - Use class-validator decorators for payload validation
+   - Define both the event payload and response type (for MessagePattern)
+
+3. **Register in module** — add the handler to the `controllers` array of the domain module
+
+4. **Create test stub** at `tests/unit/<domain>/<event-name>.handler.spec.ts`:
+   - Test payload processing logic
+   - Test error handling paths
+   - Mock only external dependencies (database, HTTP clients)
+
+5. **Verify** — run `pnpm build` and `pnpm test`

package/templates/recipes/ai-context/claude/commands/add-endpoint.md

@@ -0,0 +1,69 @@
+# Add API Endpoint
+
+Scaffold a new REST API endpoint with controller, service, DTOs, and tests.
+
+## Prompt
+
+Ask the user for:
+
+1. **Resource name** (singular, e.g. `invoice`)
+2. **HTTP methods** to include (default: CRUD — GET list, GET by ID, POST, PATCH, DELETE)
+
+## Steps
+
+1. **Create the module directory** at `src/<resource>/`
+
+2. **Create the DTOs** in `src/<resource>/dto/`:
+   - `create-<resource>.dto.ts` — request body for POST
+   - `update-<resource>.dto.ts` — request body for PATCH (PartialType of create DTO)
+   - `<resource>.response.dto.ts` — response shape
+
+   ```ts
+   import { IsString, IsNotEmpty } from 'class-validator';
+   import { ApiProperty } from '@nestjs/swagger';
+
+   export class CreateInvoiceDto {
+     @ApiProperty({ description: 'Invoice number' })
+     @IsString()
+     @IsNotEmpty()
+     number: string;
+   }
+   ```
+
+3. **Create the service** at `src/<resource>/<resource>.service.ts`:
+   - One public method per endpoint
+   - Inject repository or data source as needed
+   - Keep under 200 lines — extract helpers to separate classes
+
+4. **Create the controller** at `src/<resource>/<resource>.controller.ts`:
+   - Use `@ApiTags('<resource>')` for Swagger grouping
+   - Use `@ApiOperation()` on each method
+   - Delegate all logic to the service
+
+   ```ts
+   @ApiTags('invoices')
+   @Controller('invoices')
+   export class InvoiceController {
+     constructor(private readonly invoiceService: InvoiceService) {}
+
+     @Get()
+     @ApiOperation({ summary: 'List all invoices' })
+     findAll(): Promise<InvoiceResponseDto[]> {
+       return this.invoiceService.findAll();
+     }
+   }
+   ```
+
+5. **Create the module** at `src/<resource>/<resource>.module.ts`:
+   - Register the controller and service as providers
+   - Export the service if other modules need it
+
+6. **Register in parent module** — add the new module to the `imports` array of `AppModule` or the relevant feature module
+
+7. **Create test stubs**:
+   - `tests/unit/<resource>/<resource>.service.spec.ts`
+   - `tests/unit/<resource>/<resource>.controller.spec.ts`
+   - Each test file should have `describe` blocks for every public method
+   - Include at least: happy path, invalid input, and not-found cases
+
+8. **Verify** — run `pnpm build` and `pnpm test` to confirm everything compiles and tests pass

package/templates/recipes/ai-context/claude/commands/add-job.md

@@ -0,0 +1,42 @@
+# Add Scheduled Job
+
+Scaffold a new scheduled job using `@nestjs/schedule`.
+
+## Prompt
+
+Ask the user for:
+
+1. **Job name** (e.g. `cleanup-expired-tokens`, `sync-inventory`)
+2. **Schedule** — cron expression or a `CronExpression` constant (e.g. `EVERY_HOUR`, `EVERY_DAY_AT_MIDNIGHT`)
+
+## Steps
+
+1. **Create the job** at `src/jobs/<job-name>.job.ts`:
+
+   ```ts
+   import { Injectable, Logger } from '@nestjs/common';
+   import { Cron, CronExpression } from '@nestjs/schedule';
+
+   @Injectable()
+   export class CleanupExpiredTokensJob {
+     private readonly logger = new Logger(CleanupExpiredTokensJob.name);
+
+     @Cron(CronExpression.EVERY_DAY_AT_MIDNIGHT)
+     async handle(): Promise<void> {
+       this.logger.log('Starting cleanup of expired tokens');
+       // job logic
+       this.logger.log('Cleanup complete');
+     }
+   }
+   ```
+
+2. **Extract business logic** — if the job does more than orchestration, create a dedicated service and inject it. Keep the job class focused on scheduling concerns only.
+
+3. **Register in module** — add the job class to the `providers` array of the relevant module. Ensure `ScheduleModule.forRoot()` is imported in `AppModule`.
+
+4. **Create test stub** at `tests/unit/jobs/<job-name>.job.spec.ts`:
+   - Call the `handle()` method directly — do not test cron scheduling
+   - Test success and error paths
+   - Mock injected services
+
+5. **Verify** — run `pnpm build` and `pnpm test`

package/templates/recipes/ai-context/claude/commands/migrate.md

@@ -0,0 +1,69 @@
+# Database Migration
+
+Create and run database migrations.
+
+## TypeORM
+
+### Create a migration
+
+```bash
+pnpm typeorm migration:create src/database/migrations/<MigrationName>
+```
+
+### Generate a migration from entity changes
+
+```bash
+pnpm typeorm migration:generate src/database/migrations/<MigrationName> -d src/database/data-source.ts
+```
+
+### Run pending migrations
+
+```bash
+pnpm typeorm migration:run -d src/database/data-source.ts
+```
+
+### Revert the last migration
+
+```bash
+pnpm typeorm migration:revert -d src/database/data-source.ts
+```
+
+### Rules
+
+- Migration class names use PascalCase with a timestamp prefix (auto-generated)
+- Each migration must implement both `up()` and `down()` methods
+- Never modify a migration that has already been applied in any environment
+- Test both `up` and `down` directions locally before committing
+
+## Prisma
+
+### Create a migration
+
+```bash
+pnpm prisma migrate dev --name <migration-name>
+```
+
+### Apply migrations in production
+
+```bash
+pnpm prisma migrate deploy
+```
+
+### Reset the database (development only)
+
+```bash
+pnpm prisma migrate reset
+```
+
+### Generate Prisma client after schema changes
+
+```bash
+pnpm prisma generate
+```
+
+### Rules
+
+- Migration names use kebab-case (e.g. `add-user-email-index`)
+- Edit `prisma/schema.prisma` first, then generate the migration
+- Never edit migration SQL files after they have been applied
+- Always run `pnpm prisma generate` after schema changes

package/templates/recipes/ai-context/copilot/base.md

@@ -0,0 +1,71 @@
+# GitHub Copilot Instructions
+
+## Project Overview
+
+This is a NestJS application using Fastify, built with TypeScript and managed with pnpm.
+
+## Code Conventions
+
+### Imports
+
+- Use `@/*` path alias for all internal imports (maps to `src/*`)
+- Never use relative paths like `../../`
+
+### Architecture
+
+- 3-layer architecture: Controller -> Service -> Repository
+- Controllers: HTTP concerns only, delegate to services
+- Services: business logic, max 200 lines, no private methods
+- Extract helpers into separate injectable classes
+
+### File Naming
+
+- Services: `<name>.service.ts`
+- Controllers: `<name>.controller.ts`
+- Modules: `<name>.module.ts`
+- Entities: `<name>.entity.ts`
+- DTOs: `<name>.dto.ts` inside `dto/` subdirectory
+- Use descriptive suffixes for non-standard classes: `.processor.ts`, `.importer.ts`, `.scheduler.ts`
+
+### DTOs and Validation
+
+- Use `class-validator` decorators on all request DTOs
+- Use `class-transformer` for response serialization
+- Add `@ApiProperty()` to every DTO property for Swagger
+
+### Modules
+
+- Organize by feature domain, not by technical layer
+- Each feature gets its own module directory under `src/`
+- Export only what other modules need
+
+### Error Handling
+
+- Use NestJS built-in exceptions (`NotFoundException`, `BadRequestException`, etc.)
+- Let the global exception filter handle unexpected errors
+- Never catch exceptions just to rethrow them
+
+## Testing
+
+- 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
+- E2E tests: `tests/e2e/` with `.e2e-spec.ts` suffix
+- Mock only external dependencies — never mock code you own
+- Use `Test.createTestingModule()` from `@nestjs/testing`
+- Test factories go in `tests/factories/`
+
+## Commands
+
+- `pnpm start:dev` — start with file watching
+- `pnpm build` — compile to `dist/`
+- `pnpm test` — run unit tests
+- `pnpm test:integration` — run integration tests
+- `pnpm test:e2e` — run e2e tests
+- `pnpm test:cov` — run tests with coverage
+
+## Commits
+
+Use Conventional Commits: `<type>(<scope>): <description>`
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`