create-forgeon 0.1.27 → 0.1.30

package/package.json

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

package/src/modules/executor.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { ensureModuleExists } from './registry.mjs';
 import { writeModuleDocs } from './docs.mjs';
 import { applyI18nModule } from './i18n.mjs';
+import { applyLoggerModule } from './logger.mjs';
 
 function ensureForgeonLikeProject(targetRoot) {
   const requiredPaths = [
@@ -22,6 +23,7 @@ function ensureForgeonLikeProject(targetRoot) {
 
 const MODULE_APPLIERS = {
   i18n: applyI18nModule,
+  logger: applyLoggerModule,
 };
 
 export function applyModulePreset({ moduleId, targetRoot, packageRoot }) {

package/src/modules/executor.test.mjs

@@ -140,7 +140,7 @@ describe('addModule', () => {
       const appTsx = fs.readFileSync(path.join(projectRoot, 'apps', 'web', 'src', 'App.tsx'), 'utf8');
       assert.match(appTsx, /@forgeon\/i18n-web/);
       assert.match(appTsx, /react-i18next/);
-      assert.match(appTsx, /checkApiHealth/);
+      assert.match(appTsx, /ui:labels\.language/);
 
       const i18nWebPackage = fs.readFileSync(
         path.join(projectRoot, 'packages', 'i18n-web', 'package.json'),
@@ -184,13 +184,14 @@ describe('addModule', () => {
       const enCommon = JSON.parse(
         fs.readFileSync(path.join(projectRoot, 'resources', 'i18n', 'en', 'common.json'), 'utf8'),
       );
-      assert.equal(enCommon.checkApiHealth, 'Check API health');
-      assert.equal(enCommon.languages.english, 'English');
+      assert.equal(enCommon.actions.ok, 'OK');
+      assert.equal(enCommon.nav.next, 'Next');
 
       const enErrors = JSON.parse(
         fs.readFileSync(path.join(projectRoot, 'resources', 'i18n', 'en', 'errors.json'), 'utf8'),
       );
-      assert.equal(enErrors.notFound, 'Resource not found');
+      assert.equal(enErrors.http.NOT_FOUND, 'Resource not found');
+      assert.equal(enErrors.validation.VALIDATION_ERROR, 'Validation error');
 
       const webPackage = fs.readFileSync(path.join(projectRoot, 'apps', 'web', 'package.json'), 'utf8');
       assert.match(webPackage, /"i18next":/);
@@ -202,6 +203,7 @@ describe('addModule', () => {
       const i18nTs = fs.readFileSync(path.join(projectRoot, 'apps', 'web', 'src', 'i18n.ts'), 'utf8');
       assert.match(i18nTs, /initReactI18next/);
       assert.match(i18nTs, /\.\.\/\.\.\/\.\.\/resources\/i18n\/en\/common\.json/);
+      assert.match(i18nTs, /\.\.\/\.\.\/\.\.\/resources\/i18n\/en\/ui\.json/);
       assert.doesNotMatch(i18nTs, /I18N_DEFAULT_LANG/);
 
       const rootPackage = fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8');
@@ -241,4 +243,85 @@ describe('addModule', () => {
       fs.rmSync(targetRoot, { recursive: true, force: true });
     }
   });
+
+  it('applies logger module on top of scaffold without i18n', () => {
+    const targetRoot = mkTmp('forgeon-module-logger-');
+    const projectRoot = path.join(targetRoot, 'demo-logger');
+    const templateRoot = path.join(packageRoot, 'templates', 'base');
+
+    try {
+      scaffoldProject({
+        templateRoot,
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-logger',
+        frontend: 'react',
+        db: 'prisma',
+        i18nEnabled: false,
+        proxy: 'caddy',
+      });
+
+      const result = addModule({
+        moduleId: 'logger',
+        targetRoot: projectRoot,
+        packageRoot,
+      });
+
+      assert.equal(result.applied, true);
+      assert.match(result.message, /applied/);
+      assert.equal(
+        fs.existsSync(path.join(projectRoot, 'packages', 'logger', 'package.json')),
+        true,
+      );
+
+      const apiPackage = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'package.json'), 'utf8');
+      assert.match(apiPackage, /@forgeon\/logger/);
+      assert.match(apiPackage, /pnpm --filter @forgeon\/logger build/);
+
+      const appModule = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'src', 'app.module.ts'), 'utf8');
+      assert.match(appModule, /@forgeon\/logger/);
+      assert.match(appModule, /loggerConfig/);
+      assert.match(appModule, /loggerEnvSchema/);
+      assert.match(appModule, /ForgeonLoggerModule/);
+
+      const mainTs = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'src', 'main.ts'), 'utf8');
+      assert.match(mainTs, /ForgeonLoggerService/);
+      assert.match(mainTs, /ForgeonHttpLoggingInterceptor/);
+      assert.match(mainTs, /bufferLogs: true/);
+      assert.match(mainTs, /app\.useLogger\(app\.get\(ForgeonLoggerService\)\);/);
+      assert.match(mainTs, /app\.useGlobalInterceptors\(app\.get\(ForgeonHttpLoggingInterceptor\)\);/);
+
+      const apiDockerfile = fs.readFileSync(
+        path.join(projectRoot, 'apps', 'api', 'Dockerfile'),
+        'utf8',
+      );
+      assert.match(apiDockerfile, /COPY packages\/logger\/package\.json packages\/logger\/package\.json/);
+      assert.match(apiDockerfile, /COPY packages\/logger packages\/logger/);
+      assert.match(apiDockerfile, /RUN pnpm --filter @forgeon\/logger build/);
+
+      const apiEnv = fs.readFileSync(path.join(projectRoot, 'apps', 'api', '.env.example'), 'utf8');
+      assert.match(apiEnv, /LOGGER_LEVEL=log/);
+      assert.match(apiEnv, /LOGGER_HTTP_ENABLED=true/);
+      assert.match(apiEnv, /LOGGER_REQUEST_ID_HEADER=x-request-id/);
+
+      const dockerEnv = fs.readFileSync(
+        path.join(projectRoot, 'infra', 'docker', '.env.example'),
+        'utf8',
+      );
+      assert.match(dockerEnv, /LOGGER_LEVEL=log/);
+      assert.match(dockerEnv, /LOGGER_HTTP_ENABLED=true/);
+      assert.match(dockerEnv, /LOGGER_REQUEST_ID_HEADER=x-request-id/);
+
+      const compose = fs.readFileSync(path.join(projectRoot, 'infra', 'docker', 'compose.yml'), 'utf8');
+      assert.match(compose, /LOGGER_LEVEL: \$\{LOGGER_LEVEL\}/);
+      assert.match(compose, /LOGGER_HTTP_ENABLED: \$\{LOGGER_HTTP_ENABLED\}/);
+      assert.match(compose, /LOGGER_REQUEST_ID_HEADER: \$\{LOGGER_REQUEST_ID_HEADER\}/);
+
+      const moduleDoc = fs.readFileSync(result.docsPath, 'utf8');
+      assert.match(moduleDoc, /Logger/);
+      assert.match(moduleDoc, /Status: implemented/);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
 });

package/src/modules/logger.mjs

@@ -0,0 +1,241 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { copyRecursive, writeJson } from '../utils/fs.mjs';
+
+function copyFromPreset(packageRoot, targetRoot, relativePath) {
+  const source = path.join(packageRoot, 'templates', 'module-presets', 'logger', relativePath);
+  if (!fs.existsSync(source)) {
+    throw new Error(`Missing logger preset template: ${source}`);
+  }
+  const destination = path.join(targetRoot, relativePath);
+  copyRecursive(source, destination);
+}
+
+function ensureDependency(packageJson, name, version) {
+  if (!packageJson.dependencies) {
+    packageJson.dependencies = {};
+  }
+  packageJson.dependencies[name] = version;
+}
+
+function ensureLineAfter(content, anchorLine, lineToInsert) {
+  if (content.includes(lineToInsert)) {
+    return content;
+  }
+
+  const index = content.indexOf(anchorLine);
+  if (index < 0) {
+    return `${content.trimEnd()}\n${lineToInsert}\n`;
+  }
+
+  const insertAt = index + anchorLine.length;
+  return `${content.slice(0, insertAt)}\n${lineToInsert}${content.slice(insertAt)}`;
+}
+
+function ensureLineBefore(content, anchorLine, lineToInsert) {
+  if (content.includes(lineToInsert)) {
+    return content;
+  }
+
+  const index = content.indexOf(anchorLine);
+  if (index < 0) {
+    return `${content.trimEnd()}\n${lineToInsert}\n`;
+  }
+
+  return `${content.slice(0, index)}${lineToInsert}\n${content.slice(index)}`;
+}
+
+function upsertEnvLines(filePath, lines) {
+  let content = '';
+  if (fs.existsSync(filePath)) {
+    content = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+  }
+
+  const keys = new Set(
+    content
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => line.split('=')[0]),
+  );
+
+  const append = [];
+  for (const line of lines) {
+    const key = line.split('=')[0];
+    if (!keys.has(key)) {
+      append.push(line);
+    }
+  }
+
+  const next =
+    append.length > 0 ? `${content.trimEnd()}\n${append.join('\n')}\n` : `${content.trimEnd()}\n`;
+  fs.writeFileSync(filePath, next.replace(/^\n/, ''), 'utf8');
+}
+
+function patchApiPackage(targetRoot) {
+  const packagePath = path.join(targetRoot, 'apps', 'api', 'package.json');
+  if (!fs.existsSync(packagePath)) {
+    return;
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+  if (!packageJson.scripts) {
+    packageJson.scripts = {};
+  }
+
+  const loggerBuild = 'pnpm --filter @forgeon/logger build';
+  const currentPredev = packageJson.scripts.predev;
+  if (typeof currentPredev === 'string') {
+    if (!currentPredev.includes(loggerBuild)) {
+      if (currentPredev.includes('pnpm --filter @forgeon/core build')) {
+        packageJson.scripts.predev = currentPredev.replace(
+          'pnpm --filter @forgeon/core build',
+          `pnpm --filter @forgeon/core build && ${loggerBuild}`,
+        );
+      } else {
+        packageJson.scripts.predev = `${loggerBuild} && ${currentPredev}`;
+      }
+    }
+  } else {
+    packageJson.scripts.predev = loggerBuild;
+  }
+
+  ensureDependency(packageJson, '@forgeon/logger', 'workspace:*');
+  writeJson(packagePath, packageJson);
+}
+
+function patchMain(targetRoot) {
+  const filePath = path.join(targetRoot, 'apps', 'api', 'src', 'main.ts');
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+  content = ensureLineBefore(
+    content,
+    "import { NestFactory } from '@nestjs/core';",
+    "import { ForgeonHttpLoggingInterceptor, ForgeonLoggerService } from '@forgeon/logger';",
+  );
+
+  content = content.replace(
+    'const app = await NestFactory.create(AppModule);',
+    'const app = await NestFactory.create(AppModule, { bufferLogs: true });',
+  );
+
+  if (!content.includes('app.useLogger(app.get(ForgeonLoggerService));')) {
+    content = content.replace(
+      '  const coreConfigService = app.get(CoreConfigService);',
+      `  const coreConfigService = app.get(CoreConfigService);
+  app.useLogger(app.get(ForgeonLoggerService));
+  app.useGlobalInterceptors(app.get(ForgeonHttpLoggingInterceptor));`,
+    );
+  }
+
+  fs.writeFileSync(filePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function patchAppModule(targetRoot) {
+  const filePath = path.join(targetRoot, 'apps', 'api', 'src', 'app.module.ts');
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+
+  content = ensureLineAfter(
+    content,
+    "import { dbPrismaConfig, dbPrismaEnvSchema, DbPrismaModule } from '@forgeon/db-prisma';",
+    "import { ForgeonLoggerModule, loggerConfig, loggerEnvSchema } from '@forgeon/logger';",
+  );
+
+  content = content.replace(
+    'load: [coreConfig, dbPrismaConfig, i18nConfig],',
+    'load: [coreConfig, dbPrismaConfig, i18nConfig, loggerConfig],',
+  );
+  content = content.replace(
+    'load: [coreConfig, dbPrismaConfig],',
+    'load: [coreConfig, dbPrismaConfig, loggerConfig],',
+  );
+  content = content.replace(
+    'validate: createEnvValidator([coreEnvSchema, dbPrismaEnvSchema, i18nEnvSchema]),',
+    'validate: createEnvValidator([coreEnvSchema, dbPrismaEnvSchema, i18nEnvSchema, loggerEnvSchema]),',
+  );
+  content = content.replace(
+    'validate: createEnvValidator([coreEnvSchema, dbPrismaEnvSchema]),',
+    'validate: createEnvValidator([coreEnvSchema, dbPrismaEnvSchema, loggerEnvSchema]),',
+  );
+
+  content = ensureLineAfter(content, '    CoreErrorsModule,', '    ForgeonLoggerModule,');
+
+  fs.writeFileSync(filePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function patchApiDockerfile(targetRoot) {
+  const dockerfilePath = path.join(targetRoot, 'apps', 'api', 'Dockerfile');
+  if (!fs.existsSync(dockerfilePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(dockerfilePath, 'utf8').replace(/\r\n/g, '\n');
+
+  content = ensureLineAfter(
+    content,
+    'COPY packages/db-prisma/package.json packages/db-prisma/package.json',
+    'COPY packages/logger/package.json packages/logger/package.json',
+  );
+  content = ensureLineAfter(
+    content,
+    'COPY packages/db-prisma packages/db-prisma',
+    'COPY packages/logger packages/logger',
+  );
+
+  content = content.replace(/^RUN pnpm --filter @forgeon\/logger build\r?\n?/gm, '');
+  content = ensureLineBefore(
+    content,
+    'RUN pnpm --filter @forgeon/api prisma:generate',
+    'RUN pnpm --filter @forgeon/logger build',
+  );
+
+  fs.writeFileSync(dockerfilePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function patchCompose(targetRoot) {
+  const composePath = path.join(targetRoot, 'infra', 'docker', 'compose.yml');
+  if (!fs.existsSync(composePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(composePath, 'utf8').replace(/\r\n/g, '\n');
+  if (!content.includes('LOGGER_LEVEL: ${LOGGER_LEVEL}')) {
+    content = content.replace(
+      /^(\s+API_PREFIX:.*)$/m,
+      `$1
+      LOGGER_LEVEL: \${LOGGER_LEVEL}
+      LOGGER_HTTP_ENABLED: \${LOGGER_HTTP_ENABLED}
+      LOGGER_REQUEST_ID_HEADER: \${LOGGER_REQUEST_ID_HEADER}`,
+    );
+  }
+
+  fs.writeFileSync(composePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+export function applyLoggerModule({ packageRoot, targetRoot }) {
+  copyFromPreset(packageRoot, targetRoot, path.join('packages', 'logger'));
+  patchApiPackage(targetRoot);
+  patchMain(targetRoot);
+  patchAppModule(targetRoot);
+  patchApiDockerfile(targetRoot);
+  patchCompose(targetRoot);
+
+  upsertEnvLines(path.join(targetRoot, 'apps', 'api', '.env.example'), [
+    'LOGGER_LEVEL=log',
+    'LOGGER_HTTP_ENABLED=true',
+    'LOGGER_REQUEST_ID_HEADER=x-request-id',
+  ]);
+
+  upsertEnvLines(path.join(targetRoot, 'infra', 'docker', '.env.example'), [
+    'LOGGER_LEVEL=log',
+    'LOGGER_HTTP_ENABLED=true',
+    'LOGGER_REQUEST_ID_HEADER=x-request-id',
+  ]);
+}
+

package/src/modules/registry.mjs

@@ -7,6 +7,14 @@ const MODULE_PRESETS = {
     description: 'Backend/frontend i18n wiring with locale contracts and translation resources.',
     docFragments: ['00_title', '10_overview', '20_scope', '90_status_implemented'],
   },
+  logger: {
+    id: 'logger',
+    label: 'Logger',
+    category: 'observability',
+    implemented: true,
+    description: 'Structured API logger with request id middleware and HTTP logging interceptor.',
+    docFragments: ['00_title', '10_overview', '20_scope', '90_status_implemented'],
+  },
   'jwt-auth': {
     id: 'jwt-auth',
     label: 'JWT Auth',

package/templates/base/apps/api/src/common/dto/echo-query.dto.ts

@@ -1,6 +1,6 @@
 import { IsNotEmpty } from 'class-validator';
 
-export class EchoQueryDto {
-  @IsNotEmpty({ message: 'validation.required' })
-  value!: string;
-}
+export class EchoQueryDto {
+  @IsNotEmpty({ message: 'validation.generic.required' })
+  value!: string;
+}

package/templates/base/apps/api/src/health/health.controller.ts

@@ -13,19 +13,19 @@ export class HealthController {
   getHealth(@Query('lang') lang?: string) {
     return {
       status: 'ok',
-      message: this.translate('common.ok', lang),
-      i18n: this.translate('common.languages.english', lang),
+      message: this.translate('common.actions.ok', lang),
+      i18n: 'en',
     };
   }
 
   @Get('error')
   getErrorProbe(@Query('lang') lang?: string) {
     throw new ConflictException({
-      message: this.translate('errors.emailAlreadyExists', lang),
+      message: this.translate('errors.http.CONFLICT', lang),
       details: {
         feature: 'core-errors',
         probeId: 'health.error',
-        probe: this.translate('common.probes.error', lang),
+        probe: 'Error envelope probe',
       },
     });
   }
@@ -33,7 +33,7 @@ export class HealthController {
   @Get('validation')
   getValidationProbe(@Query('value') value?: string, @Query('lang') lang?: string) {
     if (!value || value.trim().length === 0) {
-      const translatedMessage = this.translate('validation.required', lang);
+      const translatedMessage = this.translate('validation.generic.required', lang);
       throw new BadRequestException({
         message: translatedMessage,
         details: [{ field: 'value', message: translatedMessage }],

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

@@ -64,3 +64,5 @@ Must contain:
 - 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`).
+- If i18n is enabled, module-specific namespaces must be created and wired for both API and web.
+- If module is added before i18n, namespace templates must still be prepared and applied when i18n is installed later.

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

@@ -0,0 +1,171 @@
+# ROADMAP
+
+This is a living plan. Scope and priorities may change.
+
+## Current Foundation (Implemented)
+
+- [x] Canonical scaffold: NestJS API + React web + Prisma/Postgres + Docker
+- [x] Proxy preset selection: `caddy | nginx | none`
+- [x] `@forgeon/core`:
+  - [x] `core-config` (typed env config + validation)
+  - [x] `core-errors` (global envelope + exception filter)
+  - [x] `core-validation` (global validation pipe)
+- [x] `@forgeon/db-prisma` as default-applied DB module
+- [x] i18n add-module baseline:
+  - [x] `@forgeon/i18n`, `@forgeon/i18n-contracts`, `@forgeon/i18n-web`
+  - [x] shared dictionaries in `resources/i18n/*`
+  - [x] tooling: `i18n:sync`, `i18n:check`, `i18n:types`, `i18n:add`
+- [x] module diagnostics probes pattern (`/api/health/*` + web test buttons)
+
+## Standards (Accepted)
+
+- [x] `*-contracts` and `*-web` packages are ESM-first
+- [x] API runtime modules use Node-oriented TS config
+- [x] no cross-package imports via `/src/*`; only package entrypoints
+
+## Updated Priority Backlog
+
+### P0 (Immediate Must-Have)
+
+- [ ] `logger`
+  - [ ] canonical logger module
+  - [ ] requestId / correlationId propagation
+  - [ ] structured log conventions
+
+- [ ] `openapi / swagger`
+  - [ ] env toggle: `SWAGGER_ENABLED`
+  - [ ] standard setup
+  - [ ] bearer integration hook for jwt-auth
+  - [ ] `/docs` route
+
+- [ ] `jwt-auth`
+  - [ ] module split: contracts/api/web
+  - [ ] access + refresh baseline
+  - [ ] guards/strategy integration
+
+- [ ] `rbac / permissions`
+  - [ ] decorators: `@Roles()`, `@Permissions()`
+  - [ ] guard + policy helper
+  - [ ] contracts: `Role`, `Permission`
+  - [ ] integration with jwt-auth claims
+
+- [ ] `redis/queue foundation`
+  - [ ] base Redis config/service
+  - [ ] queue baseline (BullMQ or equivalent)
+  - [ ] retry and dead-letter conventions
+
+- [ ] `rate-limit`
+  - [ ] Nest Throttler add-module
+  - [ ] policies: route / user / ip
+  - [ ] error code: `TOO_MANY_REQUESTS`
+  - [ ] reverse-proxy-aware mode (`trust proxy`)
+
+- [ ] `files` (upload + storage)
+  - [ ] upload endpoints + DTO + guards
+  - [ ] storage presets: local + S3-compatible (MinIO/R2)
+  - [ ] MIME/size validation
+  - [ ] optional image processing subpackage (`sharp`)
+  - [ ] error codes: `UPLOAD_INVALID_TYPE`, `UPLOAD_TOO_LARGE`, `UPLOAD_QUOTA`
+
+### P1 (Strongly Recommended)
+
+- [ ] `testing baseline`
+  - [ ] unit + e2e presets
+  - [ ] test helpers for add-modules
+  - [ ] smoke test template for generated project
+
+- [ ] `CI quality gates`
+  - [ ] `typecheck`, `lint`, `test`, docker build smoke
+  - [ ] release gate checklist
+
+- [ ] `cache` (Redis)
+  - [ ] CacheModule preset
+  - [ ] key naming conventions
+  - [ ] shared wrapper/service
+
+- [ ] `scheduler`
+  - [ ] `@nestjs/schedule` integration
+  - [ ] task template
+  - [ ] optional distributed lock (Redis)
+
+- [ ] `mail`
+  - [ ] at least one provider preset (SMTP/Resend/SendGrid)
+  - [ ] templates: verify email, reset password
+  - [ ] optional outbox with queue
+
+- [ ] workspace `eslint/prettier` config package
+
+### P2 (Later)
+
+- [ ] frontend `http-client` module
+- [ ] frontend UI kit package
+  - [ ] migrate reusable parts from `eso-dt` (when available)
+  - [ ] extend missing primitives
+- [ ] `realtime` (ws)
+  - [ ] gateway baseline
+  - [ ] jwt auth for ws
+  - [ ] rooms + basic events
+- [ ] `webhooks` module (subject to scope validation)
+  - [ ] signed inbound verify (HMAC)
+  - [ ] signed outbound sender
+  - [ ] replay protection (timestamp/nonce)
+
+## Execution Plan (3 Sprints)
+
+### Sprint 1: Platform Baseline and Security Start
+
+Scope:
+- `logger`
+- `openapi/swagger`
+- `jwt-auth`
+- `testing baseline`
+- `CI quality gates`
+
+Definition of Done:
+- add-modules install cleanly via `create-forgeon add <module>`
+- local dev (`pnpm dev`) and docker build both pass on fresh generated project
+- each module has probe endpoint and web probe UI hook when applicable
+- docs updated in both root and template docs
+
+### Sprint 2: Authorization and Traffic Control
+
+Scope:
+- `rbac/permissions`
+- `redis/queue foundation`
+- `rate-limit`
+- `files`
+- `cache`
+
+Definition of Done:
+- claims/roles/permissions flow validated end-to-end (api + web contracts)
+- rate-limit and files include standardized error codes and envelope mapping
+- Redis-backed modules run in docker profile with documented env keys
+- at least one e2e happy-path per module
+
+### Sprint 3: Async Integrations and Frontend Foundation
+
+Scope:
+- `scheduler`
+- `mail`
+- workspace `eslint/prettier` config package
+- frontend `http-client`
+
+Definition of Done:
+- queue/scheduler/mail basic scenarios work in local + docker
+- frontend http-client consumes api contracts with typed errors
+- lint/typecheck/test/build pass through CI gate preset
+- docs include migration notes and extension points
+
+## Explicit Dependencies and Order Constraints
+
+- `rbac` depends on `jwt-auth`
+- `rate-limit` should follow Redis/queue foundation for scalable mode
+- `mail` should reuse queue foundation where possible
+- `openapi` is most useful before/with `jwt-auth` and `http-client`
+- `realtime` and `webhooks` stay post-MVP unless a concrete use-case appears
+
+## i18n Policy For Add-Modules
+
+- [ ] each add-module that introduces user-facing text defines its own namespace templates
+- [ ] if i18n is already enabled, namespace files are added during module installation
+- [ ] if module is installed first and i18n later, namespaces are merged during i18n installation

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

@@ -53,6 +53,7 @@ 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
+- if i18n is enabled, add module namespace files and wire them for both API and web
 - add docs note under docs/AI/MODULES/<module-id>.md
 - keep backward compatibility
 ```

package/templates/base/docs/README.md

@@ -2,6 +2,7 @@
 
 - `AI/PROJECT.md` - project overview and run modes
 - `AI/ARCHITECTURE.md` - monorepo design and extension model
+- `AI/ROADMAP.md` - implementation roadmap and feature priorities
 - `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

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

@@ -51,17 +51,29 @@ export class CoreExceptionFilter implements ExceptionFilter {
   private resolveCode(status: number): string {
     switch (status) {
       case HttpStatus.BAD_REQUEST:
-        return 'validation_error';
+        return 'BAD_REQUEST';
       case HttpStatus.UNAUTHORIZED:
-        return 'unauthorized';
+        return 'UNAUTHORIZED';
       case HttpStatus.FORBIDDEN:
-        return 'forbidden';
+        return 'FORBIDDEN';
       case HttpStatus.NOT_FOUND:
-        return 'not_found';
+        return 'NOT_FOUND';
       case HttpStatus.CONFLICT:
-        return 'conflict';
+        return 'CONFLICT';
+      case HttpStatus.TOO_MANY_REQUESTS:
+        return 'TOO_MANY_REQUESTS';
+      case HttpStatus.METHOD_NOT_ALLOWED:
+        return 'METHOD_NOT_ALLOWED';
+      case HttpStatus.UNPROCESSABLE_ENTITY:
+        return 'UNPROCESSABLE_ENTITY';
+      case HttpStatus.SERVICE_UNAVAILABLE:
+        return 'SERVICE_UNAVAILABLE';
+      case HttpStatus.BAD_GATEWAY:
+        return 'BAD_GATEWAY';
+      case HttpStatus.GATEWAY_TIMEOUT:
+        return 'GATEWAY_TIMEOUT';
       default:
-        return 'internal_error';
+        return 'INTERNAL_ERROR';
     }
   }