create-forgeon 0.1.23 → 0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-forgeon",
-  "version": "0.1.23",
+  "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/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"
+  }
+}
+```