create-forgeon 0.1.27 → 0.1.30

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

@@ -1,14 +1,42 @@
 {
-  "ok": "OK",
-  "checkApiHealth": "Check API health",
-  "checkErrorEnvelope": "Check error envelope",
-  "checkValidation": "Check validation (expect 400)",
-  "checkDatabase": "Check database (create user)",
-  "language": "Language",
-  "probes": {
-    "error": "Error envelope probe"
-  },
-  "languages": {
-    "english": "English"
+  "actions": {
+    "ok": "OK",
+    "cancel": "Cancel",
+    "save": "Save",
+    "delete": "Delete",
+    "edit": "Edit",
+    "create": "Create",
+    "update": "Update",
+    "confirm": "Confirm",
+    "retry": "Retry"
+  },
+  "nav": {
+    "back": "Back",
+    "next": "Next",
+    "close": "Close"
+  },
+  "state": {
+    "loading": "Loading...",
+    "empty": "No data",
+    "selected": "Selected"
+  },
+  "status": {
+    "active": "Active",
+    "inactive": "Inactive",
+    "pending": "Pending",
+    "disabled": "Disabled",
+    "archived": "Archived"
+  },
+  "time": {
+    "today": "Today",
+    "yesterday": "Yesterday",
+    "tomorrow": "Tomorrow",
+    "now": "Now"
+  },
+  "misc": {
+    "yes": "Yes",
+    "no": "No",
+    "on": "On",
+    "off": "Off"
   }
 }

package/templates/base/resources/i18n/en/errors.json

@@ -1,5 +1,33 @@
 {
-  "accessDenied": "Access denied",
-  "notFound": "Resource not found",
-  "emailAlreadyExists": "Email already exists"
+  "http": {
+    "BAD_REQUEST": "Bad request",
+    "NOT_FOUND": "Resource not found",
+    "UNAUTHORIZED": "Unauthorized",
+    "FORBIDDEN": "Access denied",
+    "CONFLICT": "Conflict",
+    "TOO_MANY_REQUESTS": "Too many requests",
+    "METHOD_NOT_ALLOWED": "Method not allowed",
+    "UNPROCESSABLE_ENTITY": "Unprocessable entity",
+    "INTERNAL_ERROR": "Internal server error",
+    "SERVICE_UNAVAILABLE": "Service unavailable",
+    "BAD_GATEWAY": "Bad gateway",
+    "GATEWAY_TIMEOUT": "Gateway timeout"
+  },
+  "network": {
+    "NETWORK_ERROR": "Network error",
+    "TIMEOUT": "Request timeout",
+    "OFFLINE": "You appear to be offline"
+  },
+  "auth": {
+    "AUTH_INVALID_CREDENTIALS": "Invalid credentials",
+    "AUTH_TOKEN_EXPIRED": "Session expired"
+  },
+  "validation": {
+    "VALIDATION_ERROR": "Validation error"
+  },
+  "files": {
+    "UPLOAD_FILE_TOO_LARGE": "File is too large",
+    "UPLOAD_INVALID_TYPE": "Invalid file type",
+    "UPLOAD_QUOTA_EXCEEDED": "Upload quota exceeded"
+  }
 }

package/templates/base/resources/i18n/en/meta.json

@@ -0,0 +1,8 @@
+{
+  "pages": {
+    "home": {
+      "title": "Forgeon Fullstack Scaffold",
+      "description": "Canonical fullstack starter with NestJS, React, and Prisma."
+    }
+  }
+}

package/templates/base/resources/i18n/en/notifications.json

@@ -0,0 +1,21 @@
+{
+  "success": {
+    "saved": "Saved successfully",
+    "updated": "Updated successfully",
+    "deleted": "Deleted successfully",
+    "copied": "Copied successfully"
+  },
+  "error": {
+    "saveFailed": "Failed to save",
+    "updateFailed": "Failed to update",
+    "deleteFailed": "Failed to delete"
+  },
+  "info": {
+    "changesDiscarded": "Changes were discarded",
+    "sessionExpired": "Your session has expired"
+  },
+  "progress": {
+    "uploading": "Uploading...",
+    "processing": "Processing..."
+  }
+}

package/templates/base/resources/i18n/en/ui.json

@@ -0,0 +1,31 @@
+{
+  "labels": {
+    "name": "Name",
+    "email": "Email",
+    "password": "Password",
+    "search": "Search",
+    "language": "Language"
+  },
+  "placeholders": {
+    "email": "Enter email",
+    "search": "Search...",
+    "password": "Enter password"
+  },
+  "titles": {
+    "home": "Home",
+    "dashboard": "Dashboard",
+    "settings": "Settings"
+  },
+  "messages": {
+    "emptyState": "Nothing to display yet",
+    "noResults": "No results found"
+  },
+  "table": {
+    "rowsPerPage": "Rows per page",
+    "noData": "No data"
+  },
+  "modal": {
+    "confirmTitle": "Please confirm",
+    "confirmText": "Are you sure you want to continue?"
+  }
+}

package/templates/base/resources/i18n/en/validation.json

@@ -1,3 +1,32 @@
 {
-  "required": "Field is required"
+  "generic": {
+    "required": "Field is required",
+    "invalid": "Invalid value",
+    "outOfRange": "Value is out of range"
+  },
+  "string": {
+    "minLength": "Value is too short",
+    "maxLength": "Value is too long",
+    "pattern": "Value does not match required format"
+  },
+  "number": {
+    "min": "Value is too small",
+    "max": "Value is too large",
+    "int": "Value must be an integer"
+  },
+  "format": {
+    "email": "Invalid email format",
+    "phone": "Invalid phone format",
+    "url": "Invalid URL format",
+    "uuid": "Invalid UUID format"
+  },
+  "date": {
+    "minDate": "Date is too early",
+    "maxDate": "Date is too late",
+    "invalidDate": "Invalid date"
+  },
+  "file": {
+    "fileTooLarge": "File is too large",
+    "invalidType": "Invalid file type"
+  }
 }

package/templates/base/scripts/i18n-add.mjs

@@ -84,9 +84,13 @@ async function listJsonFiles(folderPath) {
 }
 
 function runSyncCommand(cwd) {
-  const command = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm';
+  const command = 'pnpm i18n:sync';
   return new Promise((resolve, reject) => {
-    const child = spawn(command, ['i18n:sync'], { cwd, stdio: 'inherit' });
+    const child = spawn(command, {
+      cwd,
+      stdio: 'inherit',
+      shell: true,
+    });
     child.on('error', (error) => reject(error));
     child.on('exit', (code) => {
       if (code === 0) {
@@ -185,4 +189,3 @@ main().catch((error) => {
   printUsage();
   process.exitCode = 1;
 });
-

package/templates/docs-fragments/README/40_i18n.md

@@ -6,6 +6,7 @@ Environment keys:
 
 Resources location: `resources/i18n`.
 These dictionaries are shared by backend (`nestjs-i18n`) and frontend (`react-i18next`).
+Default namespaces: `common`, `errors`, `validation`, `ui`, `notifications`, `meta`.
 
 Packages:
 - `@forgeon/i18n`

package/templates/module-fragments/i18n/10_overview.md

@@ -8,6 +8,7 @@ Included parts:
 - `@forgeon/i18n-web` (React-side locale helpers)
 - `react-i18next` integration for frontend translations
 - shared dictionaries in `resources/i18n/*` (`en` by default) used by both API and web
+- default namespaces: `common`, `errors`, `validation`, `ui`, `notifications`, `meta`
 
 Utility commands:
 - `pnpm i18n:sync` - regenerate `I18N_LOCALES` and `I18N_NAMESPACES` from `resources/i18n`.

package/templates/module-fragments/logger/00_title.md

@@ -0,0 +1,6 @@
+# {{MODULE_LABEL}}
+
+- Id: `{{MODULE_ID}}`
+- Category: `{{MODULE_CATEGORY}}`
+- Status: {{MODULE_STATUS}}
+

package/templates/module-fragments/logger/10_overview.md

@@ -0,0 +1,10 @@
+## Overview
+
+Adds API logging primitives with a dedicated logger package.
+
+Included parts:
+- `@forgeon/logger` package
+- request-id middleware (`x-request-id` by default)
+- HTTP logging interceptor for request/response timing
+- env-driven logger config (`LOGGER_LEVEL`, `LOGGER_HTTP_ENABLED`, `LOGGER_REQUEST_ID_HEADER`)
+

package/templates/module-fragments/logger/20_scope.md

@@ -0,0 +1,11 @@
+## Applied Scope
+
+- Adds `packages/logger` workspace package
+- Wires logger config schema into API `ConfigModule` validation/load
+- Registers logger module in `AppModule`
+- Enables Nest app logger and global HTTP logging interceptor in `main.ts`
+- Updates API `predev` script to build logger package
+- Updates API Docker build stages to include `@forgeon/logger`
+- Adds logger env keys to `apps/api/.env.example` and `infra/docker/.env.example`
+- Passes logger env keys through `infra/docker/compose.yml`
+

package/templates/module-fragments/logger/90_status_implemented.md

@@ -0,0 +1,4 @@
+## Status
+
+Implemented and applied by `create-forgeon add logger`.
+

package/templates/module-presets/i18n/apps/web/src/App.tsx

@@ -11,7 +11,7 @@ type ProbeResult = {
 };
 
 export default function App() {
-  const { t } = useTranslation(['common']);
+  const { t } = useTranslation(['ui']);
   const { I18N_LOCALES, getInitialLocale, persistLocale, toLangQuery } = i18nWeb;
   const [locale, setLocale] = useState<I18nLocale>(getInitialLocale);
   const [healthResult, setHealthResult] = useState<ProbeResult | null>(null);
@@ -73,7 +73,7 @@ export default function App() {
     <main className="page">
       <h1>Forgeon Fullstack Scaffold</h1>
       <p>Default frontend preset: React + Vite + TypeScript.</p>
-      <label htmlFor="language">{t('common:language')}:</label>
+      <label htmlFor="language">{t('ui:labels.language')}:</label>
       <select
         id="language"
         value={locale}
@@ -81,20 +81,20 @@ export default function App() {
       >
         {I18N_LOCALES.map((item) => (
           <option key={item} value={item}>
-            {t(`common:languages.${item}`, { defaultValue: item })}
+            {item}
           </option>
         ))}
       </select>
       <div className="actions">
-        <button onClick={() => runProbe(setHealthResult, '/health')}>{t('common:checkApiHealth')}</button>
+        <button onClick={() => runProbe(setHealthResult, '/health')}>Check API health</button>
         <button onClick={() => runProbe(setErrorProbeResult, '/health/error')}>
-          {t('common:checkErrorEnvelope')}
+          Check error envelope
         </button>
         <button onClick={() => runProbe(setValidationProbeResult, '/health/validation')}>
-          {t('common:checkValidation')}
+          Check validation (expect 400)
         </button>
         <button onClick={() => runProbe(setDbProbeResult, '/health/db', { method: 'POST' })}>
-          {t('common:checkDatabase')}
+          Check database (create user)
         </button>
       </div>
       {renderResult('Health response', healthResult)}

package/templates/module-presets/i18n/apps/web/src/i18n.ts

@@ -3,12 +3,18 @@ import { initReactI18next } from 'react-i18next';
 import { getInitialLocale, I18N_LOCALES, type I18nLocale } from '@forgeon/i18n-web';
 import enCommon from '../../../resources/i18n/en/common.json';
 import enErrors from '../../../resources/i18n/en/errors.json';
+import enMeta from '../../../resources/i18n/en/meta.json';
+import enNotifications from '../../../resources/i18n/en/notifications.json';
+import enUi from '../../../resources/i18n/en/ui.json';
 import enValidation from '../../../resources/i18n/en/validation.json';
 
 const resources = {
   en: {
     common: enCommon,
     errors: enErrors,
+    meta: enMeta,
+    notifications: enNotifications,
+    ui: enUi,
     validation: enValidation,
   },
 } as const;

package/templates/module-presets/i18n/packages/i18n-contracts/src/generated-keys.d.ts

@@ -1,15 +1,100 @@
 /* AUTO-GENERATED BY `pnpm i18n:types`. DO NOT EDIT MANUALLY. */
 
 export type I18nTranslationKey =
-  | "common.checkApiHealth"
-  | "common.checkDatabase"
-  | "common.checkErrorEnvelope"
-  | "common.checkValidation"
-  | "common.language"
-  | "common.languages.english"
-  | "common.ok"
-  | "common.probes.error"
-  | "errors.accessDenied"
-  | "errors.emailAlreadyExists"
-  | "errors.notFound"
-  | "validation.required";
+  | "common.actions.ok"
+  | "common.actions.cancel"
+  | "common.actions.save"
+  | "common.actions.delete"
+  | "common.actions.edit"
+  | "common.actions.create"
+  | "common.actions.update"
+  | "common.actions.confirm"
+  | "common.actions.retry"
+  | "common.nav.back"
+  | "common.nav.next"
+  | "common.nav.close"
+  | "common.state.loading"
+  | "common.state.empty"
+  | "common.state.selected"
+  | "common.status.active"
+  | "common.status.inactive"
+  | "common.status.pending"
+  | "common.status.disabled"
+  | "common.status.archived"
+  | "common.time.today"
+  | "common.time.yesterday"
+  | "common.time.tomorrow"
+  | "common.time.now"
+  | "common.misc.yes"
+  | "common.misc.no"
+  | "common.misc.on"
+  | "common.misc.off"
+  | "errors.http.NOT_FOUND"
+  | "errors.http.BAD_REQUEST"
+  | "errors.http.UNAUTHORIZED"
+  | "errors.http.FORBIDDEN"
+  | "errors.http.CONFLICT"
+  | "errors.http.TOO_MANY_REQUESTS"
+  | "errors.http.METHOD_NOT_ALLOWED"
+  | "errors.http.UNPROCESSABLE_ENTITY"
+  | "errors.http.INTERNAL_ERROR"
+  | "errors.http.SERVICE_UNAVAILABLE"
+  | "errors.http.BAD_GATEWAY"
+  | "errors.http.GATEWAY_TIMEOUT"
+  | "errors.network.NETWORK_ERROR"
+  | "errors.network.TIMEOUT"
+  | "errors.network.OFFLINE"
+  | "errors.auth.AUTH_INVALID_CREDENTIALS"
+  | "errors.auth.AUTH_TOKEN_EXPIRED"
+  | "errors.validation.VALIDATION_ERROR"
+  | "errors.files.UPLOAD_FILE_TOO_LARGE"
+  | "errors.files.UPLOAD_INVALID_TYPE"
+  | "errors.files.UPLOAD_QUOTA_EXCEEDED"
+  | "meta.pages.home.title"
+  | "meta.pages.home.description"
+  | "notifications.success.saved"
+  | "notifications.success.updated"
+  | "notifications.success.deleted"
+  | "notifications.success.copied"
+  | "notifications.error.saveFailed"
+  | "notifications.error.updateFailed"
+  | "notifications.error.deleteFailed"
+  | "notifications.info.changesDiscarded"
+  | "notifications.info.sessionExpired"
+  | "notifications.progress.uploading"
+  | "notifications.progress.processing"
+  | "ui.labels.name"
+  | "ui.labels.email"
+  | "ui.labels.password"
+  | "ui.labels.search"
+  | "ui.labels.language"
+  | "ui.placeholders.email"
+  | "ui.placeholders.search"
+  | "ui.placeholders.password"
+  | "ui.titles.home"
+  | "ui.titles.dashboard"
+  | "ui.titles.settings"
+  | "ui.messages.emptyState"
+  | "ui.messages.noResults"
+  | "ui.table.rowsPerPage"
+  | "ui.table.noData"
+  | "ui.modal.confirmTitle"
+  | "ui.modal.confirmText"
+  | "validation.generic.required"
+  | "validation.generic.invalid"
+  | "validation.generic.outOfRange"
+  | "validation.string.minLength"
+  | "validation.string.maxLength"
+  | "validation.string.pattern"
+  | "validation.number.min"
+  | "validation.number.max"
+  | "validation.number.int"
+  | "validation.format.email"
+  | "validation.format.phone"
+  | "validation.format.url"
+  | "validation.format.uuid"
+  | "validation.date.minDate"
+  | "validation.date.maxDate"
+  | "validation.date.invalidDate"
+  | "validation.file.fileTooLarge"
+  | "validation.file.invalidType";

package/templates/module-presets/i18n/packages/i18n-contracts/src/generated.ts

@@ -1,7 +1,14 @@
 /* AUTO-GENERATED BY `pnpm i18n:sync`. DO NOT EDIT MANUALLY. */
 
 export const I18N_LOCALES = ["en"] as const;
-export const I18N_NAMESPACES = ["common", "errors", "validation"] as const;
+export const I18N_NAMESPACES = [
+  "common",
+  "errors",
+  "meta",
+  "notifications",
+  "ui",
+  "validation"
+] as const;
 
 export type I18nLocale = (typeof I18N_LOCALES)[number];
 export type I18nNamespace = (typeof I18N_NAMESPACES)[number];

package/templates/module-presets/logger/packages/logger/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@forgeon/logger",
+  "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",
+    "rxjs": "^7.8.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "^5.7.3"
+  }
+}
+

package/templates/module-presets/logger/packages/logger/src/forgeon-logger.module.ts

@@ -0,0 +1,17 @@
+import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
+import { ForgeonHttpLoggingInterceptor } from './http-logging.interceptor';
+import { ForgeonLoggerService } from './forgeon-logger.service';
+import { LoggerConfigModule } from './logger-config.module';
+import { RequestIdMiddleware } from './request-id.middleware';
+
+@Module({
+  imports: [LoggerConfigModule],
+  providers: [RequestIdMiddleware, ForgeonLoggerService, ForgeonHttpLoggingInterceptor],
+  exports: [LoggerConfigModule, ForgeonLoggerService, ForgeonHttpLoggingInterceptor],
+})
+export class ForgeonLoggerModule implements NestModule {
+  configure(consumer: MiddlewareConsumer): void {
+    consumer.apply(RequestIdMiddleware).forRoutes('*');
+  }
+}
+

package/templates/module-presets/logger/packages/logger/src/forgeon-logger.service.ts

@@ -0,0 +1,51 @@
+import { ConsoleLogger, Injectable, LogLevel } from '@nestjs/common';
+import { LoggerConfigService } from './logger-config.service';
+import type { LoggerLevel } from './logger-env.schema';
+
+interface HttpLogEntry {
+  method: string;
+  path: string;
+  statusCode: number;
+  durationMs: number;
+  requestId?: string;
+  ip?: string;
+}
+
+function resolveLogLevels(level: LoggerLevel): LogLevel[] {
+  switch (level) {
+    case 'error':
+      return ['error'];
+    case 'warn':
+      return ['error', 'warn'];
+    case 'log':
+      return ['error', 'warn', 'log'];
+    case 'debug':
+      return ['error', 'warn', 'log', 'debug'];
+    case 'verbose':
+      return ['error', 'warn', 'log', 'debug', 'verbose'];
+    default:
+      return ['error', 'warn', 'log'];
+  }
+}
+
+@Injectable()
+export class ForgeonLoggerService extends ConsoleLogger {
+  constructor(private readonly loggerConfig: LoggerConfigService) {
+    super('ForgeonApi');
+    this.setLogLevels(resolveLogLevels(this.loggerConfig.level));
+  }
+
+  logHttpRequest(entry: HttpLogEntry): void {
+    if (!this.loggerConfig.httpEnabled) {
+      return;
+    }
+
+    this.log(
+      JSON.stringify({
+        event: 'http.request',
+        ...entry,
+      }),
+    );
+  }
+}
+

package/templates/module-presets/logger/packages/logger/src/http-logging.interceptor.ts

@@ -0,0 +1,90 @@
+import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
+import { Observable, tap } from 'rxjs';
+import { ForgeonLoggerService } from './forgeon-logger.service';
+import { LoggerConfigService } from './logger-config.service';
+
+type HeaderValue = string | string[] | undefined;
+type HeadersRecord = Record<string, HeaderValue>;
+
+interface RequestLike {
+  method?: string;
+  originalUrl?: string;
+  url?: string;
+  ip?: string;
+  requestId?: string;
+  headers?: HeadersRecord;
+}
+
+interface ResponseLike {
+  statusCode?: number;
+}
+
+@Injectable()
+export class ForgeonHttpLoggingInterceptor implements NestInterceptor {
+  constructor(
+    private readonly logger: ForgeonLoggerService,
+    private readonly loggerConfig: LoggerConfigService,
+  ) {}
+
+  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
+    if (context.getType<'http'>() !== 'http') {
+      return next.handle();
+    }
+
+    if (!this.loggerConfig.httpEnabled) {
+      return next.handle();
+    }
+
+    const http = context.switchToHttp();
+    const request = http.getRequest<RequestLike>();
+    const response = http.getResponse<ResponseLike>();
+
+    const method = request.method ?? 'UNKNOWN';
+    const path = request.originalUrl ?? request.url ?? '/';
+    const ip = request.ip;
+    const requestId =
+      request.requestId ?? this.readHeader(request.headers, this.loggerConfig.requestIdHeader);
+    const startedAt = Date.now();
+
+    return next.handle().pipe(
+      tap({
+        next: () => {
+          this.logger.logHttpRequest({
+            method,
+            path,
+            statusCode: response.statusCode ?? 200,
+            durationMs: Date.now() - startedAt,
+            requestId,
+            ip,
+          });
+        },
+        error: () => {
+          this.logger.logHttpRequest({
+            method,
+            path,
+            statusCode: response.statusCode ?? 500,
+            durationMs: Date.now() - startedAt,
+            requestId,
+            ip,
+          });
+        },
+      }),
+    );
+  }
+
+  private readHeader(headers: HeadersRecord | undefined, name: string): string | undefined {
+    if (!headers) {
+      return undefined;
+    }
+
+    const value = headers[name.toLowerCase()];
+    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;
+  }
+}
+

package/templates/module-presets/logger/packages/logger/src/index.ts

@@ -0,0 +1,9 @@
+export * from './logger-env.schema';
+export * from './logger-config.loader';
+export * from './logger-config.service';
+export * from './logger-config.module';
+export * from './forgeon-logger.service';
+export * from './http-logging.interceptor';
+export * from './request-id.middleware';
+export * from './forgeon-logger.module';
+