spoonfeeder 0.1.0

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "spoonfeeder",
+  "version": "0.1.0",
+  "description": "NestJS project scaffolder with 112 composable recipes",
+  "author": "B.B. Jansen <bobjansen@pm.me>",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "spoonfeeder": "./dist/index.js",
+    "create-spoonfeeder": "./dist/index.js"
+  },
+  "generators": "./generators.json",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bbjansen/spoonfeeder.git"
+  },
+  "homepage": "https://github.com/bbjansen/spoonfeeder#readme",
+  "bugs": {
+    "url": "https://github.com/bbjansen/spoonfeeder/issues"
+  },
+  "keywords": [
+    "nestjs",
+    "scaffolder",
+    "cli",
+    "boilerplate",
+    "fastify",
+    "typescript",
+    "recipes",
+    "generator",
+    "nx"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "generators.json",
+    "src/generators/*/schema.json",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "jest --selectProjects unit",
+    "test:unit": "jest --selectProjects unit",
+    "test:integration": "jest --selectProjects integration",
+    "test:e2e": "jest --selectProjects e2e",
+    "test:all": "jest",
+    "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\" --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\""
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "1.3.0",
+    "@nx/devkit": "22.7.1",
+    "ejs": "5.0.2",
+    "execa": "9.6.1",
+    "fs-extra": "11.3.5",
+    "ts-morph": "28.0.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@swc/core": "1.15.24",
+    "@swc/jest": "0.2.39",
+    "@types/ejs": "3.1.5",
+    "@types/fs-extra": "11.0.4",
+    "@types/jest": "30.0.0",
+    "@types/node": "24.12.2",
+    "eslint": "9.39.4",
+    "jest": "30.3.0",
+    "prettier": "3.8.2",
+    "typescript": "5.9.3"
+  }
+}

package/src/generators/add-recipe/schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "cli": "nx",
+  "$id": "AddRecipe",
+  "title": "Add Recipe",
+  "type": "object",
+  "properties": {
+    "recipe": {
+      "type": "string",
+      "description": "Recipe ID to add",
+      "$default": { "$source": "argv", "index": 0 },
+      "x-prompt": "Which recipe do you want to add?"
+    },
+    "skipInstall": {
+      "type": "boolean",
+      "default": false,
+      "description": "Skip pnpm install after generation"
+    }
+  },
+  "required": ["recipe"]
+}

package/src/generators/list-recipes/schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "cli": "nx",
+  "$id": "ListRecipes",
+  "title": "List Recipes",
+  "type": "object",
+  "properties": {
+    "category": {
+      "type": "string",
+      "description": "Filter by category"
+    },
+    "json": {
+      "type": "boolean",
+      "default": false,
+      "description": "Output as JSON"
+    }
+  }
+}

package/src/generators/migrate-recipe/schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "cli": "nx",
+  "$id": "MigrateRecipe",
+  "title": "Migrate Recipe",
+  "type": "object",
+  "properties": {
+    "from": {
+      "type": "string",
+      "description": "Recipe ID to remove (currently installed)",
+      "x-prompt": "Which recipe do you want to migrate FROM?"
+    },
+    "to": {
+      "type": "string",
+      "description": "Recipe ID to add (replacement)",
+      "x-prompt": "Which recipe do you want to migrate TO?"
+    }
+  },
+  "required": ["from", "to"]
+}

package/src/generators/remove-recipe/schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "cli": "nx",
+  "$id": "RemoveRecipe",
+  "title": "Remove Recipe",
+  "type": "object",
+  "properties": {
+    "recipe": {
+      "type": "string",
+      "description": "Recipe ID to remove",
+      "$default": { "$source": "argv", "index": 0 },
+      "x-prompt": "Which recipe do you want to remove?"
+    },
+    "force": {
+      "type": "boolean",
+      "default": false,
+      "description": "Remove even if other recipes depend on it"
+    }
+  },
+  "required": ["recipe"]
+}

package/templates/base/.env.example.ejs

@@ -0,0 +1,3 @@
+# Application
+PORT=3000
+NODE_ENV=development

package/templates/base/README.md.ejs

@@ -0,0 +1,20 @@
+# <%= packageScope ? packageScope + '/' + name : name %>
+
+Generated with [spoonfeeder](https://github.com/spoonfeeder/spoonfeeder).
+
+## Getting Started
+
+```bash
+pnpm install
+cp .env.example .env
+pnpm start:dev
+```
+
+## Testing
+
+```bash
+pnpm test          # Unit tests
+pnpm test:e2e      # E2E tests
+pnpm test:all      # All tests
+pnpm test:cov      # Coverage
+```

package/templates/base/SECURITY.md

@@ -0,0 +1,36 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly.
+
+**Do NOT open a public issue.**
+
+Instead, send an email to **security@example.com** with:
+
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+## Response Timeline
+
+- **Acknowledgement:** Within 48 hours
+- **Initial assessment:** Within 5 business days
+- **Fix timeline:** Depends on severity (critical: 24-72 hours, high: 1 week, medium: 2 weeks)
+
+## Supported Versions
+
+| Version | Supported |
+| ------- | --------- |
+| Latest  | Yes       |
+
+## Security Best Practices
+
+This project follows:
+
+- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/)
+- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
+- Dependency scanning via `pnpm audit`
+- Secret scanning via Gitleaks (pre-commit hook)
+- Pinned dependency versions (no version ranges)

package/templates/base/commitlint.config.js

@@ -0,0 +1,15 @@
+/** @type {import('@commitlint/types').UserConfig} */
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [
+      2,
+      'always',
+      ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'chore', 'revert', 'ci', 'build'],
+    ],
+    'scope-case': [2, 'always', 'kebab-case'],
+    'subject-case': [2, 'never', ['sentence-case', 'start-case', 'pascal-case', 'upper-case']],
+    'subject-max-length': [2, 'always', 100],
+    'body-max-line-length': [2, 'always', 100],
+  },
+};

package/templates/base/docs/adr/000-template.md

@@ -0,0 +1,45 @@
+# ADR-000: [Title]
+
+## Status
+
+[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
+
+## Date
+
+YYYY-MM-DD
+
+## Context
+
+[What is the issue that we're seeing that is motivating this decision or change?]
+
+## Decision
+
+[What is the change that we're proposing and/or doing?]
+
+## Consequences
+
+### Positive
+
+- [Benefit 1]
+- [Benefit 2]
+
+### Negative
+
+- [Trade-off 1]
+- [Trade-off 2]
+
+### Risks
+
+- [Risk 1 and mitigation]
+
+## Alternatives Considered
+
+### Alternative 1: [Name]
+
+- **Pros:** [...]
+- **Cons:** [...]
+- **Why not:** [...]
+
+## References
+
+- [Link to relevant documentation]

package/templates/base/docs/adr/001-framework-selection.md

@@ -0,0 +1,54 @@
+# ADR-001: NestJS with Fastify Adapter
+
+## Status
+
+Accepted
+
+## Date
+
+2026-01-01
+
+## Context
+
+We needed a Node.js framework for building production APIs that provides:
+
+- TypeScript-first development
+- Modular architecture with dependency injection
+- High performance for microservices
+- Strong ecosystem for common patterns (auth, validation, documentation)
+
+## Decision
+
+Use NestJS with the Fastify HTTP adapter instead of Express.
+
+## Consequences
+
+### Positive
+
+- TypeScript decorators and DI provide clean, testable architecture
+- Fastify is 2-3x faster than Express for HTTP parsing
+- NestJS has first-class support for microservices, WebSockets, GraphQL
+- Large ecosystem of official and community modules
+
+### Negative
+
+- Fastify middleware differs from Express middleware (some npm packages need adaptation)
+- Learning curve for developers unfamiliar with Angular-style patterns
+
+### Risks
+
+- Fastify plugin compatibility: mitigated by testing critical plugins
+
+## Alternatives Considered
+
+### Express (standalone)
+
+- **Pros:** Most popular, largest ecosystem
+- **Cons:** No built-in DI, no TypeScript decorators, slower
+- **Why not:** Lacks architectural opinions needed for team consistency
+
+### Fastify (standalone)
+
+- **Pros:** Fast, good plugin system
+- **Cons:** No DI, no decorators, manual architecture needed
+- **Why not:** NestJS provides the architectural layer Fastify lacks

package/templates/base/docs/adr/002-error-handling-strategy.md

@@ -0,0 +1,36 @@
+# ADR-002: RFC 9457 Problem Details for Error Responses
+
+## Status
+
+Accepted
+
+## Date
+
+2026-01-15
+
+## Context
+
+APIs need a standardized error response format that is machine-readable, extensible, and compatible with industry tooling. Custom error formats require consumers to learn a bespoke schema.
+
+## Decision
+
+Use RFC 9457 (Problem Details for HTTP APIs) as the error response format. All error responses use `Content-Type: application/problem+json` with the required fields: `type`, `title`, `status`, `detail`, `instance`.
+
+Custom extensions: `traceCode` (static, grep-searchable error identifier), `errorCode` (machine-readable error type), `timestamp`, and `debugInformation` (non-production only).
+
+## Consequences
+
+### Positive
+
+- Industry standard format recognized by API gateways, monitoring tools, and client libraries
+- `traceCode` enables instant error location via grep
+- `debugInformation` separated from production responses prevents information leakage
+
+### Negative
+
+- Slightly larger response payload than a minimal custom format
+- Consumers unfamiliar with RFC 9457 may need documentation
+
+### Risks
+
+- Breaking change if migrating from a custom error format — mitigated by versioned API rollout

package/templates/base/docs/adr/003-database-strategy.md

@@ -0,0 +1,40 @@
+# ADR-003: Multiple ORM Support via Recipes
+
+## Status
+
+Accepted
+
+## Date
+
+2026-01-20
+
+## Context
+
+Different projects have different database needs. Some teams prefer schema-first (Prisma), some prefer decorator-based (TypeORM), some need lightweight SQL (Drizzle/Kysely), and some use MongoDB (Mongoose). Forcing one ORM limits adoption.
+
+## Decision
+
+Support multiple ORMs as mutually exclusive recipes: TypeORM (Postgres/MySQL), Prisma, Mongoose, Drizzle ORM, MikroORM, and Kysely. Each recipe provides a NestJS module, schema/entity examples, migration setup, and documentation.
+
+Only one ORM can be selected per project (enforced by conflict detection).
+
+## Consequences
+
+### Positive
+
+- Teams choose the ORM that fits their project and expertise
+- Each ORM recipe is self-contained with its own module, config, and migrations
+- Conflict detection prevents incompatible combinations
+
+### Negative
+
+- More recipes to maintain
+- Shared patterns (seeding, factories) must be adapted per ORM
+
+## Alternatives Considered
+
+### TypeORM only
+
+- **Pros:** Single solution, less maintenance
+- **Cons:** Not every project needs a full ORM; excludes Prisma and Drizzle fans
+- **Why not:** Limiting choice reduces boilerplate adoption

package/templates/base/docs/adr/004-authentication-architecture.md

@@ -0,0 +1,44 @@
+# ADR-004: Composable Authentication via Recipes
+
+## Status
+
+Accepted
+
+## Date
+
+2026-02-01
+
+## Context
+
+Authentication requirements vary widely: some projects need JWT only, others need social OAuth, some need 2FA/MFA, enterprise projects need RBAC with fine-grained permissions.
+
+## Decision
+
+Provide authentication as composable recipes that can be combined:
+
+- `jwt-auth` — Base JWT with access/refresh tokens
+- `passport` — Multi-strategy Passport.js support
+- `api-keys` — API key authentication for service-to-service
+- `oauth-google/github/apple` — Social login strategies
+- `oauth2-introspection` — RFC 7662 opaque token validation
+- `dpop` — RFC 9449 proof-of-possession
+- `rbac-casl` — Role-based access control with CASL
+- `auth-flows` — Signup, email verification, password reset
+- `mfa-totp` — Two-factor authentication with TOTP
+
+## Consequences
+
+### Positive
+
+- Teams pick exactly what they need — no unused auth code
+- Each recipe is independently testable and documented
+- Social OAuth strategies follow identical Passport patterns for consistency
+
+### Negative
+
+- Some recipes depend on others (`auth-flows` requires `jwt-auth`)
+- Teams must understand which recipes to combine for their use case
+
+### Risks
+
+- Misconfigured auth is a security risk — mitigated by documentation and sensible defaults

package/templates/base/docs/adr/005-deployment-strategy.md

@@ -0,0 +1,40 @@
+# ADR-005: Multi-Target Deployment Templates
+
+## Status
+
+Accepted
+
+## Date
+
+2026-02-15
+
+## Context
+
+Projects deploy to different targets: Docker/Kubernetes for container orchestration, Serverless Framework for Lambda, Terraform for infrastructure-as-code. Each requires different config files.
+
+## Decision
+
+Provide deployment as selectable recipes during project scaffolding:
+
+- `dockerfile` — Multi-stage Docker build with dumb-init
+- `docker-compose` — Full-stack local dev with Postgres + Redis
+- `kubernetes` — Deployment, Service, ConfigMap, Ingress, HPA manifests
+- `serverless-framework` — AWS Lambda deployment
+- `terraform` — ECS Fargate module with ALB, IAM, security groups
+
+## Consequences
+
+### Positive
+
+- Teams get production-ready deployment configs out of the box
+- Multiple targets can be selected (e.g., Dockerfile + Kubernetes)
+- Terraform module is modular and extensible
+
+### Negative
+
+- Config files need customization for each project's specific infrastructure
+- Kubernetes manifests assume nginx ingress class
+
+### Risks
+
+- Outdated base images — mitigated by Renovate/Dependabot recipe

package/templates/base/docs/adr/006-testing-strategy.md

@@ -0,0 +1,41 @@
+# ADR-006: Three-Layer Testing with Testcontainers
+
+## Status
+
+Accepted
+
+## Date
+
+2026-02-20
+
+## Context
+
+Effective testing requires different layers: fast unit tests for business logic, integration tests with real databases, and E2E tests for the HTTP boundary. Mocking databases in integration tests leads to false confidence.
+
+## Decision
+
+Use a three-layer testing strategy:
+
+- **Unit tests** (`tests/unit/`) — Mock external dependencies only, fast execution
+- **Integration tests** (`tests/integration/`) — Real databases via Testcontainers, test module wiring
+- **E2E tests** (`tests/e2e/`) — Full app via Supertest, test HTTP boundary
+
+Tests live in `tests/` at the project root, mirroring the `src/` structure.
+
+## Consequences
+
+### Positive
+
+- Integration tests catch real database issues that mocks miss
+- Testcontainers provide disposable, isolated database instances
+- Three layers give confidence at different granularities
+
+### Negative
+
+- Integration tests are slower (container startup)
+- Requires Docker for integration tests
+- CI pipeline needs Docker-in-Docker or service containers
+
+### Risks
+
+- Flaky tests from container timeouts — mitigated by 30s timeout and health checks

package/templates/base/docs/adr/007-scaffolder-architecture.md

@@ -0,0 +1,64 @@
+# ADR-007: Generate-and-Own Scaffolder vs Config-as-Code (Projen)
+
+## Status
+
+Accepted
+
+## Date
+
+2026-02-25
+
+## Context
+
+We needed a tool to scaffold new NestJS projects with standardized patterns, recipes, and configurations. Two main approaches exist:
+
+1. **Generate-and-own** — A CLI generates a project once. The generated files are fully owned by the team. No runtime dependency on the scaffolder.
+2. **Config-as-code (Projen)** — Project configuration is managed by code. Running `npx projen` regenerates config files. Manual edits to managed files are overwritten.
+
+[Projen](https://projen.io/) is the most popular config-as-code tool in the Node.js ecosystem, originally built for AWS CDK projects.
+
+## Decision
+
+Use the **generate-and-own** approach via `spoonfeeder`, a CLI scaffolder built with `@clack/prompts`.
+
+## Consequences
+
+### Positive
+
+- **Zero lock-in** — Generated projects have no dependency on spoonfeeder
+- **Full ownership** — Teams can modify any generated file (tsconfig, eslint, package.json) directly
+- **No learning curve** — Developers edit files normally, no Projen API to learn
+- **Composable recipes** — 100+ recipes can be mixed and matched at generation time
+- **Framework-agnostic output** — Generated projects are standard NestJS, not Projen-managed
+
+### Negative
+
+- **No automatic updates** — When the boilerplate improves, existing projects don't get updates automatically
+- **Drift** — Projects may diverge from the standard over time
+- **One-time generation** — Adding a recipe after project creation requires manual integration
+
+### Alternatives Considered
+
+#### Projen
+
+- **Pros:** Managed config files stay in sync, automatic dependency updates, synthesized from code
+- **Cons:** High lock-in (manual edits overwritten), steep learning curve (must learn Projen API to change a tsconfig option), primarily designed for AWS CDK, team friction ("why can't I just edit package.json?")
+- **Why not:** Our team prioritizes developer autonomy and minimal tooling. Projen's value proposition (managed config) becomes a liability when teams need to customize beyond what the Projen construct exposes.
+
+#### Nx Generators
+
+- **Pros:** Powerful AST transforms, can modify existing files safely, integrated with Nx workspace
+- **Cons:** Requires Nx adoption for all projects, heavier than needed for one-time scaffolding
+- **Why not:** Not all projects need Nx. The scaffolder should work for standalone apps too.
+
+#### Yeoman
+
+- **Pros:** Established ecosystem, full generator lifecycle
+- **Cons:** Heavyweight, declining community, verbose API
+- **Why not:** `@clack/prompts` provides a better developer experience with less code.
+
+## References
+
+- [Projen documentation](https://projen.io/)
+- [@clack/prompts](https://github.com/bombshell-dev/clack)
+- [create-t3-app](https://create.t3.gg/) — inspiration for the generate-and-own pattern

package/templates/base/docs/adr/008-recipe-system.md

@@ -0,0 +1,47 @@
+# ADR-008: Composable Recipe System
+
+## Status
+
+Accepted
+
+## Date
+
+2026-03-01
+
+## Context
+
+A general-purpose boilerplate needs to support many optional features (databases, auth, caching, cloud providers, deployment). Shipping everything in one monolithic template would create bloated projects with unused dependencies.
+
+## Decision
+
+Implement a composable recipe system where each feature is an independent recipe with:
+
+- Dependencies (exact versions, no ranges)
+- Template files (source code, config)
+- Environment variables
+- Conflict declarations (mutually exclusive recipes)
+- Dependency declarations (required prerequisites)
+- AI context (CLAUDE.md sections, Cursor rules, Copilot instructions)
+- README documentation with links
+
+Recipes are selected interactively during project scaffolding and merged into the base template.
+
+## Consequences
+
+### Positive
+
+- Projects only include what they need — no unused dependencies
+- Recipes are independently maintainable and testable
+- Conflict detection prevents incompatible combinations (e.g., Pino + Winston)
+- Smart defaults per project type reduce decision fatigue
+- Cloud-aware defaults auto-select relevant services
+
+### Negative
+
+- Recipe count (100+) can be overwhelming in the CLI prompt
+- Some recipes interact in ways not captured by simple conflict/requires declarations
+- Recipe template files may conflict with each other when writing to the same directory
+
+### Risks
+
+- Version drift between recipe dependencies — mitigated by exact version pinning and periodic dependency audits