create-forgeon 0.1.21 → 0.1.23

package/README.md

@@ -1,8 +1,14 @@
-# create-forgeon
-
-CLI package for generating Forgeon fullstack monorepo projects.
-
-## Usage
+# create-forgeon
+
+CLI package for generating Forgeon fullstack monorepo projects.
+
+> [!WARNING]
+> **Pre-release package. Do not use in production before `1.0.0`.**
+> The project is under active development: each patch can add changes and may introduce breaking regressions.
+>
+> ![warning](https://img.shields.io/badge/STATUS-PRE--RELEASE%20DO%20NOT%20USE-red)
+
+## Usage
 
 ```bash
 npx create-forgeon@latest my-app --i18n true --proxy caddy

package/package.json

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

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'),
@@ -198,8 +202,6 @@ describe('addModule', () => {
       assert.match(rootPackage, /"i18n:sync"/);
       assert.match(rootPackage, /"i18n:check"/);
       assert.match(rootPackage, /"i18n:types"/);
-      assert.match(rootPackage, /postinstall/);
-      assert.match(rootPackage, /pnpm i18n:sync/);
 
       const caddyDockerfile = fs.readFileSync(
         path.join(projectRoot, 'infra', 'docker', 'caddy.Dockerfile'),

package/src/modules/i18n.mjs

@@ -34,24 +34,6 @@ function ensureScript(packageJson, name, command) {
   packageJson.scripts[name] = command;
 }
 
-function ensurePostinstallStep(packageJson, command) {
-  if (!packageJson.scripts) {
-    packageJson.scripts = {};
-  }
-
-  const current = packageJson.scripts.postinstall;
-  if (!current) {
-    packageJson.scripts.postinstall = command;
-    return;
-  }
-
-  if (current.includes(command)) {
-    return;
-  }
-
-  packageJson.scripts.postinstall = `${current} && ${command}`;
-}
-
 function upsertEnvLines(filePath, lines) {
   let content = '';
   if (fs.existsSync(filePath)) {
@@ -312,7 +294,6 @@ function patchRootPackage(targetRoot) {
     'i18n:types',
     'pnpm --filter @forgeon/i18n-contracts i18n:types',
   );
-  ensurePostinstallStep(packageJson, 'pnpm i18n:sync');
   writeJson(packagePath, packageJson);
 }
 
@@ -332,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/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;
-  }
-}