create-forgeon 0.1.23 → 0.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-forgeon",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "Forgeon project generator CLI",
   "license": "MIT",
   "author": "Forgeon",

package/src/core/docs.mjs

@@ -64,11 +64,12 @@ export function generateDocs(targetRoot, options, packageRoot) {
   } else {
     readmeFragments.push('31_proxy_preset_none');
   }
-  readmeFragments.push('32_prisma_container_start');
-  if (options.i18nEnabled) {
-    readmeFragments.push('40_i18n');
-  }
-  readmeFragments.push('90_next_steps');
+  readmeFragments.push('32_prisma_container_start');
+  if (options.i18nEnabled) {
+    readmeFragments.push('40_i18n');
+  }
+  readmeFragments.push('41_error_handling');
+  readmeFragments.push('90_next_steps');
 
   const aiProjectFragments = ['00_title', '10_what_is', '20_structure_base'];
   if (options.i18nEnabled) {
@@ -80,10 +81,11 @@ export function generateDocs(targetRoot, options, packageRoot) {
   } else {
     aiProjectFragments.push('32_proxy_notes');
   }
-  if (options.i18nEnabled) {
-    aiProjectFragments.push('33_i18n_notes');
-  }
-  aiProjectFragments.push('40_change_boundaries_base');
+  if (options.i18nEnabled) {
+    aiProjectFragments.push('33_i18n_notes');
+  }
+  aiProjectFragments.push('34_error_handling');
+  aiProjectFragments.push('40_change_boundaries_base');
   if (options.proxy !== 'none') {
     aiProjectFragments.push('41_change_boundaries_docker');
   }
@@ -97,6 +99,7 @@ export function generateDocs(targetRoot, options, packageRoot) {
     aiArchitectureFragments.push('21_env_i18n');
   }
   aiArchitectureFragments.push('22_ts_module_policy');
+  aiArchitectureFragments.push('23_error_handling');
   aiArchitectureFragments.push('30_default_db', '31_docker_runtime', '32_scope_freeze');
   aiArchitectureFragments.push('40_docs_generation', '50_extension_points');
 

package/src/core/docs.test.mjs

@@ -38,14 +38,16 @@ describe('generateDocs', () => {
       const projectDoc = readFile(path.join(targetRoot, 'docs', 'AI', 'PROJECT.md'));
       const architectureDoc = readFile(path.join(targetRoot, 'docs', 'AI', 'ARCHITECTURE.md'));
 
-      assert.match(readme, /Docker\/infra: `enabled`/);
-      assert.match(readme, /Quick Start \(Docker\)/);
-      assert.match(readme, /Proxy Preset: none/);
-      assert.doesNotMatch(readme, /i18n Configuration/);
-
-      assert.match(projectDoc, /### Docker mode/);
-      assert.match(projectDoc, /Active proxy preset: `none`/);
-      assert.doesNotMatch(projectDoc, /packages\/i18n/);
+      assert.match(readme, /Docker\/infra: `enabled`/);
+      assert.match(readme, /Quick Start \(Docker\)/);
+      assert.match(readme, /Proxy Preset: none/);
+      assert.match(readme, /Error Handling \(`core-errors`\)/);
+      assert.doesNotMatch(readme, /i18n Configuration/);
+
+      assert.match(projectDoc, /### Docker mode/);
+      assert.match(projectDoc, /Active proxy preset: `none`/);
+      assert.match(projectDoc, /CoreErrorsModule/);
+      assert.doesNotMatch(projectDoc, /packages\/i18n/);
 
       assert.match(architectureDoc, /infra\/\*/);
       assert.doesNotMatch(architectureDoc, /I18N_ENABLED/);
@@ -53,9 +55,10 @@ describe('generateDocs', () => {
       assert.match(architectureDoc, /Config Strategy/);
       assert.match(architectureDoc, /TypeScript Module Policy/);
       assert.match(architectureDoc, /tsconfig\.base\.esm\.json/);
-    } finally {
-      fs.rmSync(targetRoot, { recursive: true, force: true });
-    }
+      assert.match(architectureDoc, /DbPrismaModule/);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
   });
 
   it('generates docker and caddy notes when enabled', () => {
@@ -78,12 +81,14 @@ describe('generateDocs', () => {
       const projectDoc = readFile(path.join(targetRoot, 'docs', 'AI', 'PROJECT.md'));
       const architectureDoc = readFile(path.join(targetRoot, 'docs', 'AI', 'ARCHITECTURE.md'));
 
-      assert.match(readme, /Quick Start \(Docker\)/);
-      assert.match(readme, /Proxy Preset: Caddy/);
-      assert.match(readme, /i18n Configuration/);
-
-      assert.match(projectDoc, /`infra` - Docker Compose \(always\) \+ proxy preset \(`caddy`\)/);
-      assert.match(projectDoc, /Main proxy config: `infra\/caddy\/Caddyfile`/);
+      assert.match(readme, /Quick Start \(Docker\)/);
+      assert.match(readme, /Proxy Preset: Caddy/);
+      assert.match(readme, /i18n Configuration/);
+      assert.match(readme, /Error Handling \(`core-errors`\)/);
+
+      assert.match(projectDoc, /`infra` - Docker Compose \(always\) \+ proxy preset \(`caddy`\)/);
+      assert.match(projectDoc, /Main proxy config: `infra\/caddy\/Caddyfile`/);
+      assert.match(projectDoc, /CoreExceptionFilter/);
 
       assert.match(architectureDoc, /infra\/\*/);
       assert.match(architectureDoc, /I18N_DEFAULT_LANG/);
@@ -91,8 +96,9 @@ describe('generateDocs', () => {
       assert.match(architectureDoc, /Active reverse proxy preset: `caddy`/);
       assert.match(architectureDoc, /TypeScript Module Policy/);
       assert.match(architectureDoc, /tsconfig\.base\.node\.json/);
-    } finally {
-      fs.rmSync(targetRoot, { recursive: true, force: true });
-    }
+      assert.match(architectureDoc, /DbPrismaModule/);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
   });
 });

package/src/modules/executor.test.mjs

@@ -98,6 +98,7 @@ describe('addModule', () => {
       assert.equal(fs.existsSync(path.join(projectRoot, 'tsconfig.base.esm.json')), true);
 
       const apiPackage = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'package.json'), 'utf8');
+      assert.match(apiPackage, /@forgeon\/db-prisma/);
       assert.match(apiPackage, /@forgeon\/i18n/);
       assert.match(apiPackage, /@forgeon\/i18n-contracts/);
 
@@ -110,15 +111,20 @@ describe('addModule', () => {
 
       const appModule = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'src', 'app.module.ts'), 'utf8');
       assert.match(appModule, /coreConfig/);
+      assert.match(appModule, /dbPrismaConfig/);
+      assert.match(appModule, /dbPrismaEnvSchema/);
       assert.match(appModule, /createEnvValidator/);
       assert.match(appModule, /coreEnvSchema/);
       assert.match(appModule, /i18nConfig/);
       assert.match(appModule, /i18nEnvSchema/);
       assert.match(appModule, /CoreConfigModule/);
       assert.match(appModule, /CoreErrorsModule/);
+      assert.match(appModule, /DbPrismaModule/);
 
       const mainTs = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'src', 'main.ts'), 'utf8');
       assert.match(mainTs, /CoreExceptionFilter/);
+      assert.match(mainTs, /createValidationPipe/);
+      assert.doesNotMatch(mainTs, /new ValidationPipe\(/);
 
       const forgeonI18nModule = fs.readFileSync(
         path.join(projectRoot, 'packages', 'i18n', 'src', 'forgeon-i18n.module.ts'),
@@ -225,6 +231,8 @@ describe('addModule', () => {
         'utf8',
       );
       assert.match(apiDockerfile, /RUN pnpm --filter @forgeon\/core build/);
+      assert.match(apiDockerfile, /RUN pnpm --filter @forgeon\/db-prisma build/);
+      assert.match(apiDockerfile, /COPY packages\/db-prisma\/package\.json packages\/db-prisma\/package\.json/);
     } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
     }

package/src/modules/i18n.mjs

@@ -102,6 +102,11 @@ function patchApiDockerfile(targetRoot) {
   content = ensureLineAfter(
     content,
     'COPY packages/core/package.json packages/core/package.json',
+    'COPY packages/db-prisma/package.json packages/db-prisma/package.json',
+  );
+  content = ensureLineAfter(
+    content,
+    'COPY packages/db-prisma/package.json packages/db-prisma/package.json',
     'COPY packages/i18n-contracts/package.json packages/i18n-contracts/package.json',
   );
   content = ensureLineAfter(
@@ -112,6 +117,11 @@ function patchApiDockerfile(targetRoot) {
   content = ensureLineAfter(
     content,
     'COPY packages/core packages/core',
+    'COPY packages/db-prisma packages/db-prisma',
+  );
+  content = ensureLineAfter(
+    content,
+    'COPY packages/db-prisma packages/db-prisma',
     'COPY packages/i18n-contracts packages/i18n-contracts',
   );
   content = ensureLineAfter(
@@ -122,6 +132,7 @@ function patchApiDockerfile(targetRoot) {
 
   content = content
     .replace(/^RUN pnpm --filter @forgeon\/core build\r?\n?/gm, '')
+    .replace(/^RUN pnpm --filter @forgeon\/db-prisma build\r?\n?/gm, '')
     .replace(/^RUN pnpm --filter @forgeon\/i18n-contracts build\r?\n?/gm, '')
     .replace(/^RUN pnpm --filter @forgeon\/i18n build\r?\n?/gm, '');
 
@@ -130,6 +141,11 @@ function patchApiDockerfile(targetRoot) {
     'RUN pnpm --filter @forgeon/api prisma:generate',
     'RUN pnpm --filter @forgeon/core build',
   );
+  content = ensureLineBefore(
+    content,
+    'RUN pnpm --filter @forgeon/api prisma:generate',
+    'RUN pnpm --filter @forgeon/db-prisma build',
+  );
   content = ensureLineBefore(
     content,
     'RUN pnpm --filter @forgeon/api prisma:generate',
@@ -229,10 +245,11 @@ function patchApiPackage(targetRoot) {
   ensureScript(
     packageJson,
     'predev',
-    'pnpm --filter @forgeon/i18n-contracts build && pnpm --filter @forgeon/i18n build',
+    'pnpm --filter @forgeon/core build && pnpm --filter @forgeon/db-prisma build && pnpm --filter @forgeon/i18n-contracts build && pnpm --filter @forgeon/i18n build',
   );
   ensureDependency(packageJson, '@forgeon/i18n', 'workspace:*');
   ensureDependency(packageJson, '@forgeon/i18n-contracts', 'workspace:*');
+  ensureDependency(packageJson, '@forgeon/db-prisma', 'workspace:*');
   ensureDependency(packageJson, 'nestjs-i18n', '^10.5.1');
   writeJson(packagePath, packageJson);
 }
@@ -298,6 +315,7 @@ function patchRootPackage(targetRoot) {
 }
 
 export function applyI18nModule({ packageRoot, targetRoot }) {
+  copyFromBase(packageRoot, targetRoot, path.join('packages', 'db-prisma'));
   copyFromBase(packageRoot, targetRoot, path.join('packages', 'i18n'));
   copyFromBase(packageRoot, targetRoot, path.join('resources', 'i18n'));
 

package/src/presets/i18n.mjs

@@ -9,12 +9,13 @@ export function applyI18nDisabled(targetRoot) {
   removeIfExists(path.join(targetRoot, 'resources', 'i18n'));
 
   const apiPackagePath = path.join(targetRoot, 'apps', 'api', 'package.json');
-  if (fs.existsSync(apiPackagePath)) {
-    const apiPackage = JSON.parse(fs.readFileSync(apiPackagePath, 'utf8'));
-
-    if (apiPackage.scripts) {
-      delete apiPackage.scripts.predev;
-    }
+  if (fs.existsSync(apiPackagePath)) {
+    const apiPackage = JSON.parse(fs.readFileSync(apiPackagePath, 'utf8'));
+
+    if (apiPackage.scripts) {
+      apiPackage.scripts.predev =
+        'pnpm --filter @forgeon/core build && pnpm --filter @forgeon/db-prisma build';
+    }
 
     if (apiPackage.dependencies) {
       delete apiPackage.dependencies['@forgeon/i18n'];
@@ -110,21 +111,21 @@ export function applyI18nDisabled(targetRoot) {
     appModulePath,
     `import { Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
-import { CoreConfigModule, CoreErrorsModule, coreConfig, validateCoreEnv } from '@forgeon/core';
+import { dbPrismaConfig, dbPrismaEnvSchema, DbPrismaModule } from '@forgeon/db-prisma';
+import { CoreConfigModule, CoreErrorsModule, coreConfig, coreEnvSchema, createEnvValidator } from '@forgeon/core';
 import { HealthController } from './health/health.controller';
-import { PrismaModule } from './prisma/prisma.module';
 
 @Module({
   imports: [
     ConfigModule.forRoot({
       isGlobal: true,
-      load: [coreConfig],
-      validate: validateCoreEnv,
+      load: [coreConfig, dbPrismaConfig],
+      validate: createEnvValidator([coreEnvSchema, dbPrismaEnvSchema]),
       envFilePath: '.env',
     }),
     CoreConfigModule,
     CoreErrorsModule,
-    PrismaModule,
+    DbPrismaModule,
   ],
   controllers: [HealthController],
 })

package/templates/base/apps/api/Dockerfile

@@ -4,19 +4,22 @@ WORKDIR /app
 RUN corepack enable
 
 COPY package.json pnpm-workspace.yaml tsconfig.base.json tsconfig.base.node.json tsconfig.base.esm.json ./
-COPY apps/api/package.json apps/api/package.json
-COPY apps/api/prisma apps/api/prisma
-COPY packages/core/package.json packages/core/package.json
-COPY packages/i18n/package.json packages/i18n/package.json
+COPY apps/api/package.json apps/api/package.json
+COPY apps/api/prisma apps/api/prisma
+COPY packages/core/package.json packages/core/package.json
+COPY packages/db-prisma/package.json packages/db-prisma/package.json
+COPY packages/i18n/package.json packages/i18n/package.json
 
 RUN pnpm install --frozen-lockfile=false
 
 COPY apps/api apps/api
 COPY packages/core packages/core
+COPY packages/db-prisma packages/db-prisma
 COPY packages/i18n packages/i18n
 COPY resources resources
 
 RUN pnpm --filter @forgeon/core build
+RUN pnpm --filter @forgeon/db-prisma build
 RUN pnpm --filter @forgeon/i18n build
 RUN pnpm --filter @forgeon/api prisma:generate
 RUN pnpm --filter @forgeon/api build

package/templates/base/apps/api/package.json

@@ -2,8 +2,8 @@
   "name": "@forgeon/api",
   "version": "0.1.0",
   "private": true,
-  "scripts": {
-    "predev": "pnpm --filter @forgeon/i18n build",
+  "scripts": {
+    "predev": "pnpm --filter @forgeon/core build && pnpm --filter @forgeon/db-prisma build && pnpm --filter @forgeon/i18n build",
     "build": "tsc -p tsconfig.build.json",
     "dev": "ts-node --transpile-only src/main.ts",
     "start": "node dist/main.js",
@@ -14,6 +14,7 @@
     "prisma:seed": "ts-node --transpile-only prisma/seed.ts"
   },
   "dependencies": {
+    "@forgeon/db-prisma": "workspace:*",
     "@forgeon/core": "workspace:*",
     "@forgeon/i18n": "workspace:*",
     "@nestjs/common": "^11.0.1",

package/templates/base/apps/api/src/app.module.ts

@@ -1,5 +1,6 @@
 import { Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
+import { dbPrismaConfig, dbPrismaEnvSchema, DbPrismaModule } from '@forgeon/db-prisma';
 import {
   CoreConfigModule,
   CoreErrorsModule,
@@ -10,7 +11,6 @@ import {
 import { ForgeonI18nModule, i18nConfig, i18nEnvSchema } from '@forgeon/i18n';
 import { join } from 'path';
 import { HealthController } from './health/health.controller';
-import { PrismaModule } from './prisma/prisma.module';
 
 const i18nPath = join(__dirname, '..', '..', '..', 'resources', 'i18n');
 
@@ -18,16 +18,16 @@ const i18nPath = join(__dirname, '..', '..', '..', 'resources', 'i18n');
   imports: [
     ConfigModule.forRoot({
       isGlobal: true,
-      load: [coreConfig, i18nConfig],
-      validate: createEnvValidator([coreEnvSchema, i18nEnvSchema]),
+      load: [coreConfig, dbPrismaConfig, i18nConfig],
+      validate: createEnvValidator([coreEnvSchema, dbPrismaEnvSchema, i18nEnvSchema]),
       envFilePath: '.env',
     }),
     CoreConfigModule,
     CoreErrorsModule,
+    DbPrismaModule,
     ForgeonI18nModule.register({
       path: i18nPath,
     }),
-    PrismaModule,
   ],
   controllers: [HealthController],
 })

package/templates/base/apps/api/src/main.ts

@@ -1,6 +1,9 @@
 import 'reflect-metadata';
-import { ValidationPipe } from '@nestjs/common';
-import { CoreConfigService, CoreExceptionFilter } from '@forgeon/core';
+import {
+  CoreConfigService,
+  CoreExceptionFilter,
+  createValidationPipe,
+} from '@forgeon/core';
 import { NestFactory } from '@nestjs/core';
 import { AppModule } from './app.module';
 
@@ -10,12 +13,7 @@ async function bootstrap() {
   const coreConfigService = app.get(CoreConfigService);
 
   app.setGlobalPrefix(coreConfigService.apiPrefix);
-  app.useGlobalPipes(
-    new ValidationPipe({
-      whitelist: true,
-      transform: true,
-    }),
-  );
+  app.useGlobalPipes(createValidationPipe());
   app.useGlobalFilters(app.get(CoreExceptionFilter));
 
   await app.listen(coreConfigService.port);

package/templates/base/docs/AI/ARCHITECTURE.md

@@ -1,11 +1,15 @@
-# ARCHITECTURE
-
-## Monorepo Layout
-
-- `apps/*` - deployable apps
-- `packages/*` - reusable modules/presets
-- `infra/*` - runtime infrastructure
-- `resources/*` - static assets (translations)
+# ARCHITECTURE
+
+## Monorepo Layout
+
+- `apps/*` - deployable apps
+- `packages/*` - reusable modules/presets
+- `infra/*` - runtime infrastructure
+- `resources/*` - static assets (translations)
+
+Canonical stack is fixed in this stage:
+- NestJS + React + Prisma/Postgres + Docker
+- Proxy preset can be `caddy`, `nginx`, or `none`
 
 ## Environment Flags
 
@@ -17,36 +21,48 @@
 
 ## Config Strategy
 
-- `@forgeon/core` owns base runtime config (port, API prefix, node env).
+- `@forgeon/core` owns base runtime config, global error envelope/filter, and validation pipe defaults.
 - Core config is validated with Zod and exposed through typed accessors.
 - Add-modules own and validate only their module-specific env keys.
 - i18n is an add-module; when installed, it uses its own env keys.
-
-## Default DB Stack
-
-Current default is Prisma + Postgres.
-
-- Prisma schema and migrations live in `apps/api/prisma`
-- DB access is encapsulated via `PrismaModule` (`apps/api/src/prisma`)
-
-## Future DB Presets (Not Implemented Yet)
-
-A future preset can switch DB by:
-1. Replacing `PrismaModule` with another DB module package (for example Mongo package).
-2. Updating `infra/docker/compose.yml` DB service.
-3. Updating `DATABASE_URL` and related env keys.
-4. Keeping app-level services dependent only on repository/data-access abstractions.
-
-## Future Feature Modules
 
-Reusable features should be added as workspace packages and imported by apps as needed:
+## Default DB Stack
+
+Current default is Prisma + Postgres.
+
+- Prisma schema and migrations live in `apps/api/prisma`
+- DB access is encapsulated via `DbPrismaModule` in `@forgeon/db-prisma`
+- `db-prisma` is treated as default-applied behavior in scaffold generation.
+- Future direction: this default DB layer may be extracted to an explicit add-module/preset and optionally controlled by a CLI flag.
+- Additional DB presets are out of scope for the current milestone.
+
+## Module Strategy
 
-- `packages/core` for shared backend primitives
-- Additional packages for auth presets, guards, queues, mailers, etc.
+Reusable features should be added as fullstack add-modules:
+
+- `contracts` package (shared DTO/routes/errors)
+- `api` package (NestJS integration)
+- `web` package (React integration)
+
+Reference: `docs/AI/MODULE_SPEC.md`.
 
 ## TypeScript Module Format Policy
 
-- `apps/api`, `packages/core`, and backend runtime packages use `tsconfig.base.node.json`.
-- Frontend-consumed shared packages (contracts/web helpers) use `tsconfig.base.esm.json`.
-- Contracts packages are ESM-first and imported only via package entrypoints.
+- `apps/api`, `packages/core`, and backend runtime packages use Node-oriented config:
+  - `tsconfig.base.node.json`
+- Frontend-consumed shared packages (especially contracts/web helpers) use ESM config:
+  - `tsconfig.base.esm.json`
+- Contracts packages are ESM-first and imported via package entrypoints only.
 - Cross-package imports from `/src/*` are disallowed.
+
+## Error Handling Strategy
+
+- `@forgeon/core` owns the global HTTP error envelope and filter.
+- API apps import `CoreErrorsModule` and register `CoreExceptionFilter` globally.
+- Envelope fields:
+  - `error.code`
+  - `error.message`
+  - `error.status`
+  - `error.details` (optional)
+  - `error.requestId` (optional)
+  - `error.timestamp`

package/templates/base/docs/AI/PROJECT.md

@@ -4,15 +4,16 @@
 
 A canonical fullstack monorepo scaffold intended to be reused as a project starter.
 
-## Structure
-
-- `apps/api` - NestJS backend
-- `apps/web` - frontend scaffold (default React + Vite + TS)
-- `packages/core` - shared backend core package with internal submodules (starting with `core-config`)
-- `packages/i18n` - reusable nestjs-i18n integration package
-- `infra` - Docker Compose + reverse proxy preset (nginx/caddy)
-- `resources/i18n` - translation dictionaries
-- `docs` - documentation and AI workflow prompts
+## Structure
+
+- `apps/api` - NestJS backend
+- `apps/web` - React frontend (fixed stack)
+- `packages/core` - shared backend core package (`core-config`, `core-errors`, `core-validation`)
+- `packages/db-prisma` - reusable Prisma/Postgres module (`DbPrismaModule`, `PrismaService`, config)
+- `packages/i18n` - reusable nestjs-i18n integration package
+- `infra` - Docker Compose + proxy preset (`caddy|nginx|none`)
+- `resources/i18n` - translation dictionaries
+- `docs` - documentation, AI prompts, and module contracts
 
 ## Run Modes
 
@@ -23,10 +24,20 @@ pnpm install
 pnpm dev
 ```
 
-### Docker mode
-
-```bash
-docker compose --env-file infra/docker/.env.example -f infra/docker/compose.yml up --build
-```
-
-The API uses Prisma and expects `DATABASE_URL` from env.
+### Docker mode
+
+```bash
+docker compose --env-file infra/docker/.env.example -f infra/docker/compose.yml up --build
+```
+
+The API uses Prisma and expects `DATABASE_URL` from env.
+
+If proxy preset is `none`, API is directly available on `localhost:3000`.
+
+## Error Handling
+
+`core-errors` is enabled by default.
+
+- `CoreErrorsModule` is imported in `apps/api/src/app.module.ts`.
+- `CoreExceptionFilter` is registered globally in `apps/api/src/main.ts`.
+- Throw standard Nest exceptions from controllers/services; the filter converts them to a stable envelope.

package/templates/base/docs/AI/VALIDATION.md

@@ -3,9 +3,12 @@
 ## Backend DTO Validation Standard
 
 - Use `class-validator` decorators on DTO classes.
-- Global validation is done by Nest `ValidationPipe` with:
+- Global validation is centralized in `@forgeon/core` via `createValidationPipe()`.
+- Current defaults:
   - `whitelist: true`
   - `transform: true`
+  - `validationError.target: false`
+  - `validationError.value: false`
 - Keep DTO validation messages stable and explicit.
 - For required values, use a consistent key or message pattern.
 
@@ -24,3 +27,5 @@
   - `error.status`
   - optional `error.details`
 - Validation details should be structured (not `any`).
+- `core-validation` formats validation details as:
+  - `{ field?: string, message: string }[]`

package/templates/base/packages/core/README.md

@@ -6,4 +6,5 @@ Current submodules:
 
 - `core-config` - Zod-validated env config + typed accessors for API runtime.
 - `core-errors` - global exception filter + stable error envelope shape.
+- `core-validation` - shared ValidationPipe factory with normalized validation details.
 

package/templates/base/packages/core/src/errors/core-exception.filter.ts

@@ -88,15 +88,23 @@ export class CoreExceptionFilter implements ExceptionFilter {
   }
 
   private resolveDetails(payload: unknown, status: number): AppErrorDetails | undefined {
-    if (status !== HttpStatus.BAD_REQUEST) {
+    if (typeof payload !== 'object' || payload === null) {
       return undefined;
     }
 
-    if (typeof payload !== 'object' || payload === null) {
+    const obj = payload as { message?: unknown; details?: unknown };
+
+    if (Array.isArray(obj.details)) {
+      return obj.details as AppErrorDetails;
+    }
+    if (obj.details && typeof obj.details === 'object') {
+      return obj.details as AppErrorDetails;
+    }
+
+    if (status !== HttpStatus.BAD_REQUEST) {
       return undefined;
     }
 
-    const obj = payload as { message?: unknown };
     const messages = Array.isArray(obj.message)
       ? obj.message.filter((item): item is string => typeof item === 'string')
       : typeof obj.message === 'string'

package/templates/base/packages/core/src/index.ts

@@ -1,2 +1,3 @@
 export * from './config';
 export * from './errors';
+export * from './validation';

package/templates/base/packages/core/src/validation/core-validation.pipe.ts

@@ -0,0 +1,56 @@
+import { BadRequestException, ValidationPipe } from '@nestjs/common';
+import type { ValidationErrorDetail } from '../errors';
+
+type ValidationNode = {
+  property?: string;
+  constraints?: Record<string, string>;
+  children?: ValidationNode[];
+};
+
+function toPath(parentPath: string, property: string | undefined): string {
+  if (!property || property.length === 0) {
+    return parentPath;
+  }
+  return parentPath.length > 0 ? `${parentPath}.${property}` : property;
+}
+
+function collectValidationDetails(
+  errors: ValidationNode[],
+  parentPath = '',
+): ValidationErrorDetail[] {
+  const details: ValidationErrorDetail[] = [];
+
+  for (const error of errors) {
+    const field = toPath(parentPath, error.property);
+    const constraints = error.constraints ? Object.values(error.constraints) : [];
+
+    for (const message of constraints) {
+      details.push(field.length > 0 ? { field, message } : { message });
+    }
+
+    if (Array.isArray(error.children) && error.children.length > 0) {
+      details.push(...collectValidationDetails(error.children, field));
+    }
+  }
+
+  return details;
+}
+
+export function createValidationPipe(): ValidationPipe {
+  return new ValidationPipe({
+    whitelist: true,
+    transform: true,
+    validationError: {
+      target: false,
+      value: false,
+    },
+    exceptionFactory: (errors) => {
+      const details = collectValidationDetails(errors as ValidationNode[]);
+      const firstMessage = details[0]?.message ?? 'Validation failed';
+      return new BadRequestException({
+        message: firstMessage,
+        details,
+      });
+    },
+  });
+}

package/templates/base/packages/core/src/validation/index.ts

@@ -0,0 +1 @@
+export * from './core-validation.pipe';

package/templates/base/packages/db-prisma/README.md

@@ -0,0 +1,9 @@
+# @forgeon/db-prisma
+
+Reusable Prisma/Postgres backend module.
+
+Includes:
+
+- `DbPrismaModule`
+- `PrismaService`
+- module-local config loader/service and env schema validation

package/templates/base/packages/db-prisma/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@forgeon/db-prisma",
+  "version": "0.1.0",
+  "private": true,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/config": "^4.0.2",
+    "@prisma/client": "^6.18.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "^5.7.3"
+  }
+}

package/templates/base/packages/db-prisma/src/db-prisma-config.loader.ts

@@ -0,0 +1,18 @@
+import { registerAs } from '@nestjs/config';
+import { parseDbPrismaEnv } from './db-prisma-env.schema';
+
+export const DB_PRISMA_CONFIG_NAMESPACE = 'dbPrisma';
+
+export interface DbPrismaConfigValues {
+  databaseUrl: string;
+}
+
+export const dbPrismaConfig = registerAs(
+  DB_PRISMA_CONFIG_NAMESPACE,
+  (): DbPrismaConfigValues => {
+    const env = parseDbPrismaEnv(process.env);
+    return {
+      databaseUrl: env.DATABASE_URL,
+    };
+  },
+);

package/templates/base/packages/db-prisma/src/db-prisma-config.service.ts

@@ -0,0 +1,12 @@
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { DB_PRISMA_CONFIG_NAMESPACE } from './db-prisma-config.loader';
+
+@Injectable()
+export class DbPrismaConfigService {
+  constructor(private readonly configService: ConfigService) {}
+
+  get databaseUrl(): string {
+    return this.configService.getOrThrow<string>(`${DB_PRISMA_CONFIG_NAMESPACE}.databaseUrl`);
+  }
+}

package/templates/base/packages/db-prisma/src/db-prisma-env.schema.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+
+export const dbPrismaEnvSchema = z
+  .object({
+    DATABASE_URL: z
+      .string()
+      .trim()
+      .min(1)
+      .default('postgresql://postgres:postgres@localhost:5432/app?schema=public'),
+  })
+  .passthrough();
+
+export type DbPrismaEnv = z.infer<typeof dbPrismaEnvSchema>;
+
+export function parseDbPrismaEnv(input: Record<string, unknown>): DbPrismaEnv {
+  return dbPrismaEnvSchema.parse(input);
+}

package/templates/base/packages/db-prisma/src/db-prisma.module.ts

@@ -0,0 +1,13 @@
+import { Global, Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { dbPrismaConfig } from './db-prisma-config.loader';
+import { DbPrismaConfigService } from './db-prisma-config.service';
+import { PrismaService } from './prisma.service';
+
+@Global()
+@Module({
+  imports: [ConfigModule.forFeature(dbPrismaConfig)],
+  providers: [DbPrismaConfigService, PrismaService],
+  exports: [DbPrismaConfigService, PrismaService],
+})
+export class DbPrismaModule {}

package/templates/base/packages/db-prisma/src/index.ts

@@ -0,0 +1,5 @@
+export * from './db-prisma-env.schema';
+export * from './db-prisma-config.loader';
+export * from './db-prisma-config.service';
+export * from './db-prisma.module';
+export * from './prisma.service';

package/templates/base/{apps/api/src/prisma → packages/db-prisma/src}/prisma.service.ts

@@ -1,27 +1,24 @@
-import { Injectable, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
-import { PrismaClient } from '@prisma/client';
-
-@Injectable()
-export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
-  constructor() {
-    const databaseUrl =
-      process.env.DATABASE_URL ??
-      'postgresql://postgres:postgres@localhost:5432/app?schema=public';
-
-    super({
-      datasources: {
-        db: {
-          url: databaseUrl,
-        },
-      },
-    });
-  }
-
-  async onModuleInit(): Promise<void> {
-    await this.$connect();
-  }
-
-  async onModuleDestroy(): Promise<void> {
-    await this.$disconnect();
-  }
-}
+import { Injectable, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import { PrismaClient } from '@prisma/client';
+import { DbPrismaConfigService } from './db-prisma-config.service';
+
+@Injectable()
+export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
+  constructor(configService: DbPrismaConfigService) {
+    super({
+      datasources: {
+        db: {
+          url: configService.databaseUrl,
+        },
+      },
+    });
+  }
+
+  async onModuleInit(): Promise<void> {
+    await this.$connect();
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    await this.$disconnect();
+  }
+}

package/templates/base/packages/db-prisma/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/docs-fragments/AI_ARCHITECTURE/20_env_base.md

@@ -6,6 +6,6 @@
 
 ## Config Strategy
 
-- `@forgeon/core` owns base runtime config (port, API prefix, node env).
+- `@forgeon/core` owns base runtime config, global error envelope/filter, and validation pipe defaults.
 - Core config is validated with Zod and exposed through typed accessors.
 - Add-modules own and validate only their module-specific env keys.

package/templates/docs-fragments/AI_ARCHITECTURE/23_error_handling.md

@@ -0,0 +1,11 @@
+## Error Handling Strategy
+
+- `@forgeon/core` owns the global HTTP error envelope.
+- API apps import `CoreErrorsModule` and register `CoreExceptionFilter` as a global filter.
+- Envelope fields:
+  - `error.code`
+  - `error.message`
+  - `error.status`
+  - `error.details` (optional, mainly validation context)
+  - `error.requestId` (optional, derived from `x-request-id`)
+  - `error.timestamp`

package/templates/docs-fragments/AI_ARCHITECTURE/30_default_db.md

@@ -1,7 +1,9 @@
-## Default DB Stack
-
-Current default stack is `{{DB_LABEL}}`.
-
-- Prisma schema and migrations live in `apps/api/prisma`
-- DB access is encapsulated via `PrismaModule` (`apps/api/src/prisma`)
-- Additional DB presets are intentionally out of scope for the current milestone.
+## Default DB Stack
+
+Current default stack is `{{DB_LABEL}}`.
+
+- Prisma schema and migrations live in `apps/api/prisma`
+- DB access is encapsulated via `DbPrismaModule` in `@forgeon/db-prisma`
+- `db-prisma` is currently default-applied during scaffold generation.
+- Future direction: this DB layer may be extracted into an explicit add-module/preset and optionally exposed via CLI flag(s).
+- Additional DB presets are intentionally out of scope for the current milestone.

package/templates/docs-fragments/AI_ARCHITECTURE/32_scope_freeze.md

@@ -1,5 +1,6 @@
-## Scope Freeze (Current)
-
-- Frontend preset selection is disabled (React is fixed).
-- DB preset selection is disabled (Prisma/Postgres is fixed).
-- Docker is always generated; runtime proxy is selectable (`caddy|nginx|none`).
+## Scope Freeze (Current)
+
+- Frontend preset selection is disabled (React is fixed).
+- DB preset selection is disabled (Prisma/Postgres is fixed).
+- Docker is always generated; runtime proxy is selectable (`caddy|nginx|none`).
+- DB preset flags may return in a future milestone after `db-prisma` is separated into an explicit preset/module flow.

package/templates/docs-fragments/AI_PROJECT/20_structure_base.md

@@ -2,4 +2,5 @@
 
 - `apps/api` - NestJS backend
 - `apps/web` - React frontend (`{{FRONTEND_LABEL}}`, fixed)
-- `packages/core` - shared backend core package (`core-config` and future core submodules)
+- `packages/core` - shared backend core package (`core-config`, `core-errors`, `core-validation`)
+- `packages/db-prisma` - default DB module (`DbPrismaModule`, Prisma service + config)

package/templates/docs-fragments/AI_PROJECT/34_error_handling.md

@@ -0,0 +1,7 @@
+### Error Handling
+
+`core-errors` is enabled by default.
+
+- `CoreErrorsModule` is imported in `apps/api/src/app.module.ts`.
+- `CoreExceptionFilter` is registered globally in `apps/api/src/main.ts`.
+- Controllers and services should throw standard Nest exceptions; envelope formatting is handled centrally.

package/templates/docs-fragments/README/41_error_handling.md

@@ -0,0 +1,27 @@
+## Error Handling (`core-errors`)
+
+`@forgeon/core` includes a default global exception filter (`CoreExceptionFilter`).
+
+Wiring:
+- module import: `apps/api/src/app.module.ts` (`CoreErrorsModule`)
+- global registration: `apps/api/src/main.ts` (`app.useGlobalFilters(app.get(CoreExceptionFilter))`)
+
+Usage:
+- throw standard Nest exceptions in services/controllers:
+  - `throw new ConflictException('Email already exists')`
+  - `throw new NotFoundException('Resource not found')`
+
+Response envelope:
+
+```json
+{
+  "error": {
+    "code": "conflict",
+    "message": "Email already exists",
+    "status": 409,
+    "details": [],
+    "requestId": "optional",
+    "timestamp": "2026-02-25T12:00:00.000Z"
+  }
+}
+```

package/templates/base/apps/api/src/prisma/prisma.module.ts

@@ -1,9 +0,0 @@
-import { Global, Module } from '@nestjs/common';
-import { PrismaService } from './prisma.service';
-
-@Global()
-@Module({
-  providers: [PrismaService],
-  exports: [PrismaService],
-})
-export class PrismaModule {}