create-forgeon 0.1.24 → 0.1.26

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/MODULE_CHECKS.md

@@ -0,0 +1,25 @@
+# MODULE CHECKS
+
+## Purpose
+
+Define mandatory runtime verification hooks for Forgeon modules.
+
+If a module can be validated through a safe API call, it must provide:
+
+1. A probe endpoint in API (`/api/health/*`).
+2. A probe trigger on default web page (`apps/web/src/App.tsx`).
+3. A visible result block in UI with HTTP status and JSON body.
+
+## Current Baseline Probes
+
+- `core-errors`: `GET /api/health/error` (returns error envelope, expected `409`)
+- `core-validation`: `GET /api/health/validation` without `value` (expected `400`)
+- `db-prisma`: `POST /api/health/db` (creates probe user and returns it, expected `201`)
+
+## Rules For Future Modules
+
+- Probe path should be explicit and feature-scoped (`/api/health/<feature>`).
+- Probe must be deterministic and documented (expected status + payload shape).
+- If probe writes data, it must use clearly marked probe/test records.
+- Probe should not require hidden setup beyond documented env/dependencies.
+- `create-forgeon add <module>` must wire both API probe and web probe UI when feasible.

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

@@ -63,3 +63,4 @@ Must contain:
 - Contracts package can be imported from both sides without circular dependencies.
 - Contracts package exports are stable from `dist/index` entrypoint.
 - Module has docs under `docs/AI/MODULES/<module-id>.md`.
+- If module behavior can be runtime-checked, it also includes API+Web probe hooks (see `docs/AI/MODULE_CHECKS.md`).

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/TASKS.md

@@ -48,11 +48,12 @@ Create or update create-forgeon preset flow:
 ## Add Fullstack Module
 
 ```text
-Implement `create-forgeon add <module-id>` for a fullstack feature.
-Requirements:
-- split module into contracts/api/web packages
-- contracts is source of truth for routes, DTOs, errors
-- add docs note under docs/AI/MODULES/<module-id>.md
-- keep backward compatibility
-```
+Implement `create-forgeon add <module-id>` for a fullstack feature.
+Requirements:
+- split module into contracts/api/web packages
+- contracts is source of truth for routes, DTOs, errors
+- if feasible, add module probe hooks in API (`/api/health/*`) and web diagnostics UI
+- add docs note under docs/AI/MODULES/<module-id>.md
+- keep backward compatibility
+```
 

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/docs/README.md

@@ -3,5 +3,6 @@
 - `AI/PROJECT.md` - project overview and run modes
 - `AI/ARCHITECTURE.md` - monorepo design and extension model
 - `AI/MODULE_SPEC.md` - fullstack module contract (`contracts/api/web`)
+- `AI/MODULE_CHECKS.md` - required runtime probe hooks for modules
 - `AI/VALIDATION.md` - DTO/env validation standards
 - `AI/TASKS.md` - ready-to-use Codex prompts

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/base/resources/i18n/en/common.json

@@ -1,6 +1,9 @@
 {
   "ok": "OK",
   "checkApiHealth": "Check API health",
+  "checkErrorEnvelope": "Check error envelope",
+  "checkValidation": "Check validation (expect 400)",
+  "checkDatabase": "Check database (create user)",
   "language": "Language",
   "languages": {
     "english": "English",

package/templates/base/resources/i18n/uk/common.json

@@ -1,6 +1,9 @@
 {
   "ok": "OK",
   "checkApiHealth": "Перевірити API health",
+  "checkErrorEnvelope": "Перевірити error envelope",
+  "checkValidation": "Перевірити валідацію (очікуємо 400)",
+  "checkDatabase": "Перевірити базу даних (створити користувача)",
   "language": "Мова",
   "languages": {
     "english": "Англійська",

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/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)