create-forgeon 0.1.22 → 0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-forgeon",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "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/);
@@ -78,12 +80,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/);

package/src/modules/executor.test.mjs

@@ -115,6 +115,10 @@ describe('addModule', () => {
       assert.match(appModule, /i18nConfig/);
       assert.match(appModule, /i18nEnvSchema/);
       assert.match(appModule, /CoreConfigModule/);
+      assert.match(appModule, /CoreErrorsModule/);
+
+      const mainTs = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'src', 'main.ts'), 'utf8');
+      assert.match(mainTs, /CoreExceptionFilter/);
 
       const forgeonI18nModule = fs.readFileSync(
         path.join(projectRoot, 'packages', 'i18n', 'src', 'forgeon-i18n.module.ts'),

package/src/modules/i18n.mjs

@@ -313,11 +313,6 @@ export function applyI18nModule({ packageRoot, targetRoot }) {
     targetRoot,
     path.join('apps', 'api', 'src', 'health', 'health.controller.ts'),
   );
-  copyFromBase(
-    packageRoot,
-    targetRoot,
-    path.join('apps', 'api', 'src', 'common', 'filters', 'app-exception.filter.ts'),
-  );
 
   patchI18nPackage(targetRoot);
   patchApiPackage(targetRoot);

package/src/presets/i18n.mjs

@@ -110,10 +110,9 @@ export function applyI18nDisabled(targetRoot) {
     appModulePath,
     `import { Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
-import { CoreConfigModule, coreConfig, validateCoreEnv } from '@forgeon/core';
+import { CoreConfigModule, CoreErrorsModule, coreConfig, validateCoreEnv } from '@forgeon/core';
 import { HealthController } from './health/health.controller';
 import { PrismaModule } from './prisma/prisma.module';
-import { AppExceptionFilter } from './common/filters/app-exception.filter';
 
 @Module({
   imports: [
@@ -124,15 +123,15 @@ import { AppExceptionFilter } from './common/filters/app-exception.filter';
       envFilePath: '.env',
     }),
     CoreConfigModule,
+    CoreErrorsModule,
     PrismaModule,
   ],
   controllers: [HealthController],
-  providers: [AppExceptionFilter],
-})
-export class AppModule {}
-`,
-    'utf8',
-  );
+})
+export class AppModule {}
+`,
+    'utf8',
+  );
 
   const healthControllerPath = path.join(
     targetRoot,
@@ -166,80 +165,8 @@ export class HealthController {
     'utf8',
   );
 
-  const filterPath = path.join(
-    targetRoot,
-    'apps',
-    'api',
-    'src',
-    'common',
-    'filters',
-    'app-exception.filter.ts',
-  );
-  fs.writeFileSync(
-    filterPath,
-    `import {
-  ArgumentsHost,
-  Catch,
-  ExceptionFilter,
-  HttpException,
-  HttpStatus,
-  Injectable,
-} from '@nestjs/common';
-import { Response } from 'express';
-
-@Injectable()
-@Catch()
-export class AppExceptionFilter implements ExceptionFilter {
-  catch(exception: unknown, host: ArgumentsHost): void {
-    const context = host.switchToHttp();
-    const response = context.getResponse<Response>();
-
-    const status =
-      exception instanceof HttpException
-        ? exception.getStatus()
-        : HttpStatus.INTERNAL_SERVER_ERROR;
-
-    const payload =
-      exception instanceof HttpException
-        ? exception.getResponse()
-        : { message: 'Internal server error' };
-
-    const message =
-      typeof payload === 'object' && payload !== null && 'message' in payload
-        ? Array.isArray((payload as { message?: unknown }).message)
-          ? String((payload as { message: unknown[] }).message[0] ?? 'Internal server error')
-          : String((payload as { message?: unknown }).message ?? 'Internal server error')
-        : typeof payload === 'string'
-          ? payload
-          : 'Internal server error';
-
-    response.status(status).json({
-      error: {
-        code: this.resolveCode(status),
-        message,
-      },
-    });
-  }
-
-  private resolveCode(status: number): string {
-    switch (status) {
-      case HttpStatus.BAD_REQUEST:
-        return 'validation_error';
-      case HttpStatus.UNAUTHORIZED:
-        return 'unauthorized';
-      case HttpStatus.FORBIDDEN:
-        return 'forbidden';
-      case HttpStatus.NOT_FOUND:
-        return 'not_found';
-      case HttpStatus.CONFLICT:
-        return 'conflict';
-      default:
-        return 'internal_error';
-    }
-  }
-}
-`,
-    'utf8',
+  removeIfExists(
+    path.join(targetRoot, 'apps', 'api', 'src', 'common', 'filters', 'app-exception.filter.ts'),
   );
 }
 

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

@@ -2,6 +2,7 @@ import { Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
 import {
   CoreConfigModule,
+  CoreErrorsModule,
   coreConfig,
   coreEnvSchema,
   createEnvValidator,
@@ -10,7 +11,6 @@ import { ForgeonI18nModule, i18nConfig, i18nEnvSchema } from '@forgeon/i18n';
 import { join } from 'path';
 import { HealthController } from './health/health.controller';
 import { PrismaModule } from './prisma/prisma.module';
-import { AppExceptionFilter } from './common/filters/app-exception.filter';
 
 const i18nPath = join(__dirname, '..', '..', '..', 'resources', 'i18n');
 
@@ -23,13 +23,13 @@ const i18nPath = join(__dirname, '..', '..', '..', 'resources', 'i18n');
       envFilePath: '.env',
     }),
     CoreConfigModule,
+    CoreErrorsModule,
     ForgeonI18nModule.register({
       path: i18nPath,
     }),
-    PrismaModule,
-  ],
-  controllers: [HealthController],
-  providers: [AppExceptionFilter],
-})
-export class AppModule {}
+    PrismaModule,
+  ],
+  controllers: [HealthController],
+})
+export class AppModule {}
 

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

@@ -1,12 +1,11 @@
 import 'reflect-metadata';
 import { ValidationPipe } from '@nestjs/common';
-import { CoreConfigService } from '@forgeon/core';
+import { CoreConfigService, CoreExceptionFilter } from '@forgeon/core';
 import { NestFactory } from '@nestjs/core';
 import { AppModule } from './app.module';
-import { AppExceptionFilter } from './common/filters/app-exception.filter';
-
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
 
   const coreConfigService = app.get(CoreConfigService);
 
@@ -14,10 +13,10 @@ async function bootstrap() {
   app.useGlobalPipes(
     new ValidationPipe({
       whitelist: true,
-      transform: true,
-    }),
-  );
-  app.useGlobalFilters(app.get(AppExceptionFilter));
+      transform: true,
+    }),
+  );
+  app.useGlobalFilters(app.get(CoreExceptionFilter));
 
   await app.listen(coreConfigService.port);
 }

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

@@ -5,4 +5,5 @@ Shared backend core package.
 Current submodules:
 
 - `core-config` - Zod-validated env config + typed accessors for API runtime.
+- `core-errors` - global exception filter + stable error envelope shape.
 

package/templates/base/packages/core/src/errors/core-errors.module.ts

@@ -0,0 +1,8 @@
+import { Module } from '@nestjs/common';
+import { CoreExceptionFilter } from './core-exception.filter';
+
+@Module({
+  providers: [CoreExceptionFilter],
+  exports: [CoreExceptionFilter],
+})
+export class CoreErrorsModule {}

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

@@ -0,0 +1,137 @@
+import {
+  ArgumentsHost,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+  HttpStatus,
+  Injectable,
+} from '@nestjs/common';
+import { AppErrorDetails, ValidationErrorDetail } from './error.types';
+
+type HttpLikeResponse = {
+  status: (statusCode: number) => {
+    json: (body: unknown) => void;
+  };
+};
+
+@Injectable()
+@Catch()
+export class CoreExceptionFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const context = host.switchToHttp();
+    const response = context.getResponse<HttpLikeResponse>();
+    const request = context.getRequest<{ headers?: Record<string, unknown> }>();
+
+    const status =
+      exception instanceof HttpException
+        ? exception.getStatus()
+        : HttpStatus.INTERNAL_SERVER_ERROR;
+
+    const payload =
+      exception instanceof HttpException
+        ? exception.getResponse()
+        : { message: 'Internal server error' };
+
+    const requestId = this.resolveRequestId(request?.headers);
+    const details = this.resolveDetails(payload, status);
+    const timestamp = new Date().toISOString();
+
+    response.status(status).json({
+      error: {
+        code: this.resolveCode(status),
+        message: this.resolveMessage(payload, status),
+        status,
+        ...(details !== undefined ? { details } : {}),
+        ...(requestId !== undefined ? { requestId } : {}),
+        timestamp,
+      },
+    });
+  }
+
+  private resolveCode(status: number): string {
+    switch (status) {
+      case HttpStatus.BAD_REQUEST:
+        return 'validation_error';
+      case HttpStatus.UNAUTHORIZED:
+        return 'unauthorized';
+      case HttpStatus.FORBIDDEN:
+        return 'forbidden';
+      case HttpStatus.NOT_FOUND:
+        return 'not_found';
+      case HttpStatus.CONFLICT:
+        return 'conflict';
+      default:
+        return 'internal_error';
+    }
+  }
+
+  private resolveMessage(payload: unknown, status: number): string {
+    if (status === HttpStatus.NOT_FOUND) {
+      return 'Resource not found';
+    }
+
+    if (typeof payload === 'string') {
+      return payload;
+    }
+
+    if (typeof payload === 'object' && payload !== null) {
+      const obj = payload as { message?: string | string[] };
+      if (Array.isArray(obj.message) && obj.message.length > 0) {
+        return String(obj.message[0]);
+      }
+      if (typeof obj.message === 'string' && obj.message.length > 0) {
+        return obj.message;
+      }
+    }
+
+    return status >= 500 ? 'Internal server error' : 'Request failed';
+  }
+
+  private resolveDetails(payload: unknown, status: number): AppErrorDetails | undefined {
+    if (status !== HttpStatus.BAD_REQUEST) {
+      return undefined;
+    }
+
+    if (typeof payload !== 'object' || payload === null) {
+      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'
+        ? [obj.message]
+        : [];
+
+    if (messages.length === 0) {
+      return undefined;
+    }
+
+    const details: ValidationErrorDetail[] = messages.map((message) => {
+      const field = this.extractField(message);
+      return field ? { field, message } : { message };
+    });
+
+    return details;
+  }
+
+  private resolveRequestId(headers: Record<string, unknown> | undefined): string | undefined {
+    if (!headers) {
+      return undefined;
+    }
+
+    const value = headers['x-request-id'];
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return value;
+    }
+    if (Array.isArray(value) && typeof value[0] === 'string' && value[0].trim().length > 0) {
+      return value[0];
+    }
+    return undefined;
+  }
+
+  private extractField(message: string): string | undefined {
+    const match = message.match(/^([A-Za-z0-9_.[\]-]+)\s+/);
+    return match?.[1];
+  }
+}

package/templates/base/packages/core/src/errors/error.types.ts

@@ -0,0 +1,19 @@
+export interface ValidationErrorDetail {
+  field?: string;
+  message: string;
+}
+
+export type AppErrorDetails = ValidationErrorDetail[] | Record<string, unknown>;
+
+export interface AppErrorPayload {
+  code: string;
+  message: string;
+  status: number;
+  details?: AppErrorDetails;
+  requestId?: string;
+  timestamp: string;
+}
+
+export interface AppErrorEnvelope {
+  error: AppErrorPayload;
+}

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

@@ -0,0 +1,3 @@
+export * from './error.types';
+export * from './core-exception.filter';
+export * from './core-errors.module';

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

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

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_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/common/filters/app-exception.filter.ts

@@ -1,130 +0,0 @@
-import {
-  ArgumentsHost,
-  Catch,
-  ExceptionFilter,
-  HttpException,
-  HttpStatus,
-  Injectable,
-  Optional,
-} from '@nestjs/common';
-import { I18nService } from 'nestjs-i18n';
-import { Request, Response } from 'express';
-
-@Injectable()
-@Catch()
-export class AppExceptionFilter implements ExceptionFilter {
-  constructor(@Optional() private readonly i18n?: I18nService) {}
-
-  catch(exception: unknown, host: ArgumentsHost): void {
-    const context = host.switchToHttp();
-    const response = context.getResponse<Response>();
-    const request = context.getRequest<Request>();
-
-    const status =
-      exception instanceof HttpException
-        ? exception.getStatus()
-        : HttpStatus.INTERNAL_SERVER_ERROR;
-
-    const payload =
-      exception instanceof HttpException
-        ? exception.getResponse()
-        : { message: 'Internal server error' };
-
-    const code = this.resolveCode(status);
-    const message = this.resolveMessage(payload, status, request);
-    const details = this.resolveDetails(payload);
-
-    response.status(status).json({
-      error: {
-        code,
-        message,
-        ...(details !== undefined ? { details } : {}),
-      },
-    });
-  }
-
-  private resolveCode(status: number): string {
-    switch (status) {
-      case HttpStatus.BAD_REQUEST:
-        return 'validation_error';
-      case HttpStatus.UNAUTHORIZED:
-        return 'unauthorized';
-      case HttpStatus.FORBIDDEN:
-        return 'forbidden';
-      case HttpStatus.NOT_FOUND:
-        return 'not_found';
-      case HttpStatus.CONFLICT:
-        return 'conflict';
-      default:
-        return 'internal_error';
-    }
-  }
-
-  private resolveMessage(
-    payload: unknown,
-    status: number,
-    request: Request,
-  ): string {
-    const lang = this.resolveLang(request);
-
-    if (status === HttpStatus.NOT_FOUND) {
-      return this.translate('errors.notFound', lang);
-    }
-
-    if (typeof payload === 'string') {
-      return this.translate(payload, lang);
-    }
-
-    if (typeof payload === 'object' && payload !== null) {
-      const obj = payload as { message?: string | string[] };
-      if (Array.isArray(obj.message) && obj.message.length > 0) {
-        return this.translate(obj.message[0], lang);
-      }
-      if (typeof obj.message === 'string') {
-        return this.translate(obj.message, lang);
-      }
-    }
-
-    return 'Internal server error';
-  }
-
-  private resolveDetails(payload: unknown): unknown {
-    if (typeof payload !== 'object' || payload === null) {
-      return undefined;
-    }
-
-    const obj = payload as { message?: string | string[]; error?: string };
-    if (Array.isArray(obj.message) && obj.message.length > 1) {
-      return obj.message;
-    }
-
-    return undefined;
-  }
-
-  private resolveLang(request: Request): string | undefined {
-    const queryLang = request.query?.lang;
-    if (typeof queryLang === 'string' && queryLang.length > 0) {
-      return queryLang;
-    }
-
-    const header = request.headers['accept-language'];
-    if (typeof header === 'string' && header.length > 0) {
-      return header.split(',')[0].trim();
-    }
-
-    return undefined;
-  }
-
-  private translate(keyOrMessage: string, lang?: string): string {
-    if (!this.i18n) {
-      return keyOrMessage;
-    }
-
-    const translated = this.i18n.t(keyOrMessage, {
-      lang,
-      defaultValue: keyOrMessage,
-    });
-
-    return typeof translated === 'string' ? translated : keyOrMessage;
-  }
-}