spoonfeeder 0.1.0

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

@@ -0,0 +1,78 @@
+# Runbook: [Service/Issue Name]
+
+## Overview
+
+- **Service:** [Service name]
+- **Severity:** [P1/P2/P3/P4]
+- **On-call team:** [Team name]
+- **Last updated:** YYYY-MM-DD
+
+## Symptoms
+
+- [What does the user/monitoring see?]
+- [Which alerts fire?]
+- [What metrics change?]
+
+## Diagnosis
+
+### Step 1: Check service health
+
+```bash
+curl https://api.example.com/health/ready
+```
+
+### Step 2: Check logs
+
+```bash
+# CloudWatch
+aws logs filter-log-events --log-group-name /ecs/app --filter-pattern "ERROR"
+
+# Kubernetes
+kubectl logs -l app=api --tail=100 | grep ERROR
+```
+
+### Step 3: Check database
+
+```bash
+# Connection count
+SELECT count(*) FROM pg_stat_activity;
+
+# Slow queries
+SELECT * FROM pg_stat_activity WHERE state = 'active' AND duration > interval '5 seconds';
+```
+
+## Mitigation
+
+### Quick fix
+
+[What can be done immediately to restore service?]
+
+### Rollback
+
+```bash
+# Kubernetes
+kubectl rollout undo deployment/api
+
+# ECS
+aws ecs update-service --cluster prod --service api --task-definition api:PREVIOUS_VERSION
+```
+
+## Resolution
+
+[Steps to permanently fix the issue]
+
+## Post-Incident
+
+- [ ] Incident documented
+- [ ] Root cause identified
+- [ ] Prevention measures implemented
+- [ ] Monitoring/alerting updated
+- [ ] Team notified
+
+## Escalation
+
+| Level | Contact             | When               |
+| ----- | ------------------- | ------------------ |
+| L1    | On-call engineer    | First response     |
+| L2    | Team lead           | After 30 minutes   |
+| L3    | Engineering manager | After 1 hour or P1 |

package/templates/base/docs/sla-slo.md

@@ -0,0 +1,36 @@
+# Service Level Objectives (SLOs)
+
+## API Availability
+
+| Metric     | Target                      | Measurement                    |
+| ---------- | --------------------------- | ------------------------------ |
+| Uptime     | 99.9% (8.76h downtime/year) | Health check endpoint          |
+| Error rate | < 0.1% of requests          | 5xx responses / total requests |
+
+## API Latency
+
+| Percentile | Target   | Measurement                      |
+| ---------- | -------- | -------------------------------- |
+| p50        | < 100ms  | Response time from load balancer |
+| p95        | < 500ms  | Response time from load balancer |
+| p99        | < 1000ms | Response time from load balancer |
+
+## Error Budget
+
+Monthly error budget: 100% - 99.9% = 0.1% = ~43 minutes/month
+
+| Budget used | Action                                            |
+| ----------- | ------------------------------------------------- |
+| < 50%       | Normal development velocity                       |
+| 50-80%      | Increase testing, slower rollouts                 |
+| > 80%       | Freeze non-critical changes, focus on reliability |
+| 100%        | Incident response, rollback recent changes        |
+
+## Monitoring & Alerting
+
+| Alert                | Threshold              | Channel           |
+| -------------------- | ---------------------- | ----------------- |
+| Error rate spike     | > 1% for 5 minutes     | PagerDuty + Slack |
+| Latency spike (p95)  | > 2s for 5 minutes     | Slack             |
+| Health check failure | 3 consecutive failures | PagerDuty         |
+| Certificate expiry   | < 30 days              | Email             |

package/templates/base/dot-editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

package/templates/base/dot-github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,33 @@
+---
+name: Bug Report
+about: Report a bug to help us improve
+labels: bug
+---
+
+## Description
+
+<!-- A clear description of the bug -->
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+
+## Expected Behavior
+
+<!-- What should happen -->
+
+## Actual Behavior
+
+<!-- What actually happens -->
+
+## Environment
+
+- Node.js version:
+- pnpm version:
+- OS:
+
+## Additional Context
+
+<!-- Logs, screenshots, or other relevant information -->

package/templates/base/dot-github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,21 @@
+---
+name: Feature Request
+about: Suggest a new feature
+labels: enhancement
+---
+
+## Problem Statement
+
+<!-- What problem does this feature solve? -->
+
+## Proposed Solution
+
+<!-- How should it work? -->
+
+## Alternatives Considered
+
+<!-- What other approaches did you consider? -->
+
+## Additional Context
+
+<!-- Mockups, examples, or references -->

package/templates/base/dot-github/pull_request_template.md

@@ -0,0 +1,32 @@
+## Description
+
+<!-- What does this PR do? Why is it needed? -->
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Refactoring (no functional changes)
+- [ ] Documentation update
+- [ ] Dependency update
+
+## Related Issues
+
+<!-- Link to related issues: Closes #123, Fixes #456 -->
+
+## Test Plan
+
+- [ ] Unit tests added/updated
+- [ ] Integration tests added/updated (if applicable)
+- [ ] E2E tests added/updated (if applicable)
+- [ ] Manual testing performed
+
+## Checklist
+
+- [ ] Code follows project coding standards
+- [ ] Self-reviewed the code
+- [ ] No `TODO` or `FIXME` comments left behind
+- [ ] No secrets or credentials in the code
+- [ ] Documentation updated (if applicable)
+- [ ] Breaking changes documented

package/templates/base/dot-gitignore

@@ -0,0 +1,28 @@
+# Compiled output
+dist/
+build/
+
+# Dependencies
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Testing
+coverage/
+
+# Logs
+*.log
+logs/

package/templates/base/dot-husky/commit-msg

@@ -0,0 +1 @@
+pnpm exec commitlint --edit $1

package/templates/base/dot-husky/pre-commit

@@ -0,0 +1 @@
+pnpm exec lint-staged

package/templates/base/dot-husky/pre-push

@@ -0,0 +1,2 @@
+pnpm exec tsc --noEmit
+pnpm test:unit --passWithNoTests

package/templates/base/dot-npmrc

@@ -0,0 +1 @@
+save-exact=true

package/templates/base/dot-nvmrc

@@ -0,0 +1 @@
+22

package/templates/base/dot-prettierrc

@@ -0,0 +1,8 @@
+{
+  "singleQuote": true,
+  "semi": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "trailingComma": "all",
+  "endOfLine": "lf"
+}

package/templates/base/eslint.config.mjs

@@ -0,0 +1,35 @@
+// @ts-check
+import eslint from '@eslint/js';
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  {
+    ignores: ['eslint.config.mjs', 'dist/**', 'coverage/**'],
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked,
+  eslintPluginPrettierRecommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.jest,
+      },
+      sourceType: 'commonjs',
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-floating-promises': 'warn',
+      '@typescript-eslint/no-unsafe-argument': 'warn',
+      'prettier/prettier': ['error', { endOfLine: 'auto' }],
+    },
+  },
+);

package/templates/base/jest.config.ts

@@ -0,0 +1,56 @@
+import type { Config } from 'jest';
+
+const swcTransform: [string, Record<string, unknown>] = [
+  '@swc/jest',
+  {
+    jsc: {
+      parser: {
+        syntax: 'typescript',
+        decorators: true,
+      },
+      transform: {
+        legacyDecorator: true,
+        decoratorMetadata: true,
+      },
+      target: 'es2023',
+    },
+    module: {
+      type: 'commonjs',
+    },
+  },
+];
+
+const config: Config = {
+  projects: [
+    {
+      displayName: 'unit',
+      testMatch: ['<rootDir>/tests/unit/**/*.spec.ts'],
+      moduleFileExtensions: ['js', 'json', 'ts'],
+      transform: { '^.+\\.ts$': swcTransform },
+      moduleNameMapper: { '^@/(.*)$': '<rootDir>/src/$1' },
+      testEnvironment: 'node',
+    },
+    {
+      displayName: 'integration',
+      testMatch: ['<rootDir>/tests/integration/**/*.spec.ts'],
+      moduleFileExtensions: ['js', 'json', 'ts'],
+      transform: { '^.+\\.ts$': swcTransform },
+      moduleNameMapper: { '^@/(.*)$': '<rootDir>/src/$1' },
+      testEnvironment: 'node',
+      testTimeout: 30000,
+    },
+    {
+      displayName: 'e2e',
+      testMatch: ['<rootDir>/tests/e2e/**/*.spec.ts'],
+      moduleFileExtensions: ['js', 'json', 'ts'],
+      transform: { '^.+\\.ts$': swcTransform },
+      moduleNameMapper: { '^@/(.*)$': '<rootDir>/src/$1' },
+      testEnvironment: 'node',
+      testTimeout: 15000,
+    },
+  ],
+  collectCoverageFrom: ['src/**/*.ts', '!src/**/*.spec.ts', '!src/main.ts'],
+  coverageDirectory: 'coverage',
+};
+
+export default config;

package/templates/base/nest-cli.json.ejs

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true,
+    "builder": "swc",
+    "typeCheck": true
+  }
+}

package/templates/base/nx.json

@@ -0,0 +1,3 @@
+{
+  "$schema": "./node_modules/nx/schemas/nx-schema.json"
+}

package/templates/base/package.json.ejs

@@ -0,0 +1,78 @@
+{
+  "name": "<%= packageScope ? packageScope + '/' + name : name %>",
+  "version": "0.0.1",
+  "description": "",
+  "private": true,
+  "engines": {
+    "node": ">=22.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "nest build && tsc-alias",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "start": "nest start",
+    "start:dev": "nest start --watch",
+    "start:debug": "nest start --debug --watch",
+    "start:prod": "node dist/main",
+    "lint": "eslint \"{src,tests}/**/*.ts\" --fix",
+    "test": "jest --selectProjects unit",
+    "test:unit": "jest --selectProjects unit",
+    "test:integration": "jest --selectProjects integration",
+    "test:e2e": "jest --selectProjects e2e",
+    "test:all": "jest",
+    "test:watch": "jest --selectProjects unit --watch",
+    "test:cov": "jest --selectProjects unit integration --coverage",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "@fastify/etag": "6.0.0",
+    "@nestjs/common": "11.1.19",
+    "@nestjs/config": "4.0.4",
+    "@nestjs/core": "11.1.19",
+    "@nestjs/platform-fastify": "11.1.19",
+    "class-transformer": "0.5.1",
+    "class-validator": "0.15.1",
+    "fastify": "5.8.4",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "20.5.0",
+    "@commitlint/config-conventional": "20.5.0",
+    "@eslint/eslintrc": "3.3.5",
+    "@eslint/js": "9.39.4",
+    "@nestjs/cli": "11.0.19",
+    "@nestjs/schematics": "11.0.10",
+    "@nestjs/testing": "11.1.19",
+    "@swc/cli": "0.8.1",
+    "@swc/core": "1.15.24",
+    "@swc/jest": "0.2.39",
+    "@types/jest": "30.0.0",
+    "@types/node": "24.12.2",
+    "@types/supertest": "7.2.0",
+    "eslint": "9.39.4",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-prettier": "5.5.5",
+    "globals": "17.4.0",
+    "husky": "9.1.7",
+    "jest": "30.3.0",
+    "nx": "22.7.1",
+    "lint-staged": "16.4.0",
+    "prettier": "3.8.2",
+    "supertest": "7.2.2",
+    "ts-loader": "9.5.7",
+    "ts-node": "10.9.2",
+    "tsc-alias": "1.8.16",
+    "tsconfig-paths": "4.2.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.58.1"
+  },
+  "lint-staged": {
+    "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
+    "*.{json,md,yml,yaml}": ["prettier --write"]
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["@swc/core"]
+  }
+}

package/templates/base/src/shared/constants/error-codes.constant.ts

@@ -0,0 +1,30 @@
+export const ERROR_CODES = {
+  // Auth
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  FORBIDDEN: 'FORBIDDEN',
+  TOKEN_EXPIRED: 'TOKEN_EXPIRED',
+  INVALID_TOKEN: 'INVALID_TOKEN',
+
+  // Validation
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  INVALID_REQUEST: 'INVALID_REQUEST',
+
+  // Resource
+  NOT_FOUND: 'NOT_FOUND',
+  CONFLICT: 'CONFLICT',
+  ALREADY_EXISTS: 'ALREADY_EXISTS',
+
+  // Rate limiting
+  TOO_MANY_REQUESTS: 'TOO_MANY_REQUESTS',
+
+  // Server
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+  SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
+  REQUESTER_ERROR: 'REQUESTER_ERROR',
+
+  // General
+  BAD_REQUEST: 'BAD_REQUEST',
+  HTTP_ERROR: 'HTTP_ERROR',
+} as const;
+
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];

package/templates/base/src/shared/constants/http.constant.ts

@@ -0,0 +1,134 @@
+/**
+ * Standard HTTP and API constants.
+ * Override via environment variables or ConfigService where noted.
+ */
+
+// ─── Rate Limiting ───────────────────────────────────────────────────────────
+
+/** Default requests per window for global rate limiting */
+export const RATE_LIMIT_DEFAULT = 100;
+
+/** Default rate limit window in seconds */
+export const RATE_LIMIT_WINDOW_SECONDS = 60;
+
+/** Rate limit for authentication endpoints (stricter) */
+export const RATE_LIMIT_AUTH = 10;
+
+/** Rate limit window for auth endpoints in seconds */
+export const RATE_LIMIT_AUTH_WINDOW_SECONDS = 300;
+
+// ─── Caching ─────────────────────────────────────────────────────────────────
+
+/** Default cache TTL in seconds */
+export const CACHE_TTL_DEFAULT = 300;
+
+/** Short-lived cache TTL (frequently changing data) */
+export const CACHE_TTL_SHORT = 30;
+
+/** Long-lived cache TTL (static/rarely changing data) */
+export const CACHE_TTL_LONG = 3600;
+
+/** Cache TTL for user sessions in seconds */
+export const CACHE_TTL_SESSION = 1800;
+
+// ─── Timeouts ────────────────────────────────────────────────────────────────
+
+/** Default request timeout in milliseconds */
+export const REQUEST_TIMEOUT_MS = 30_000;
+
+/** Database query timeout in milliseconds */
+export const DB_QUERY_TIMEOUT_MS = 10_000;
+
+/** External HTTP call timeout in milliseconds */
+export const HTTP_CLIENT_TIMEOUT_MS = 15_000;
+
+/** Lambda/serverless function timeout in milliseconds */
+export const LAMBDA_TIMEOUT_MS = 29_000;
+
+// ─── Pagination ──────────────────────────────────────────────────────────────
+
+/** Default page size for paginated endpoints */
+export const PAGE_SIZE_DEFAULT = 20;
+
+/** Maximum allowed page size */
+export const PAGE_SIZE_MAX = 100;
+
+/** Minimum allowed page size */
+export const PAGE_SIZE_MIN = 1;
+
+// ─── Request Limits ──────────────────────────────────────────────────────────
+
+/** Maximum request body size in bytes (10 MB) */
+export const MAX_BODY_SIZE_BYTES = 10 * 1024 * 1024;
+
+/** Maximum file upload size in bytes (50 MB) */
+export const MAX_FILE_SIZE_BYTES = 50 * 1024 * 1024;
+
+/** Maximum number of files per upload */
+export const MAX_FILES_PER_UPLOAD = 10;
+
+// ─── Security ────────────────────────────────────────────────────────────────
+
+/** JWT access token expiration */
+export const JWT_ACCESS_TOKEN_EXPIRY = '15m';
+
+/** JWT refresh token expiration */
+export const JWT_REFRESH_TOKEN_EXPIRY = '7d';
+
+/** Password hash rounds (bcrypt) */
+export const PASSWORD_HASH_ROUNDS = 12;
+
+/** Maximum failed login attempts before lockout */
+export const MAX_LOGIN_ATTEMPTS = 5;
+
+/** Account lockout duration in minutes */
+export const ACCOUNT_LOCKOUT_MINUTES = 15;
+
+// ─── Retry & Circuit Breaker ─────────────────────────────────────────────────
+
+/** Default retry attempts for external calls */
+export const RETRY_MAX_ATTEMPTS = 3;
+
+/** Initial retry delay in milliseconds */
+export const RETRY_INITIAL_DELAY_MS = 200;
+
+/** Retry backoff multiplier */
+export const RETRY_BACKOFF_MULTIPLIER = 2;
+
+/** Circuit breaker failure threshold (percentage) */
+export const CIRCUIT_BREAKER_THRESHOLD = 50;
+
+/** Circuit breaker reset timeout in milliseconds */
+export const CIRCUIT_BREAKER_RESET_MS = 30_000;
+
+// ─── Health Checks ───────────────────────────────────────────────────────────
+
+/** Memory heap threshold for health check (200 MB) */
+export const HEALTH_MEMORY_HEAP_THRESHOLD = 200 * 1024 * 1024;
+
+/** Memory RSS threshold for health check (300 MB) */
+export const HEALTH_MEMORY_RSS_THRESHOLD = 300 * 1024 * 1024;
+
+/** Disk storage threshold for health check (90%) */
+export const HEALTH_DISK_THRESHOLD_PERCENT = 0.9;
+
+// ─── Connection Pools ────────────────────────────────────────────────────────
+
+/** Default database connection pool size */
+export const DB_POOL_MAX = 20;
+
+/** Minimum database pool connections */
+export const DB_POOL_MIN = 5;
+
+/** Idle connection timeout in milliseconds */
+export const DB_POOL_IDLE_TIMEOUT_MS = 30_000;
+
+/** Connection acquisition timeout in milliseconds */
+export const DB_POOL_ACQUIRE_TIMEOUT_MS = 5_000;
+
+// ─── HTTP Headers ────────────────────────────────────────────────────────────
+
+export const HEADER_CORRELATION_ID = 'x-correlation-id';
+export const HEADER_REQUEST_ID = 'x-request-id';
+export const HEADER_IDEMPOTENCY_KEY = 'idempotency-key';
+export const HEADER_API_VERSION = 'x-api-version';

package/templates/base/src/shared/constants/index.ts

@@ -0,0 +1,2 @@
+export { ERROR_CODES, type ErrorCode } from './error-codes.constant';
+export * from './http.constant';

package/templates/base/src/shared/decorators/api-paginated-response.decorator.ts

@@ -0,0 +1,10 @@
+import { applyDecorators, Type } from '@nestjs/common';
+
+/**
+ * Decorator placeholder for paginated API responses.
+ * When @nestjs/swagger is installed, this can be expanded with ApiExtraModels and ApiOkResponse.
+ * Without swagger, it's a no-op decorator.
+ */
+export function ApiPaginatedResponse<T>(dataDto: Type<T>) {
+  return applyDecorators();
+}