create-forgeon 0.2.5 → 0.2.6

package/package.json

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

package/src/modules/executor.mjs

@@ -6,6 +6,7 @@ import { applyDbPrismaModule } from './db-prisma.mjs';
 import { applyI18nModule } from './i18n.mjs';
 import { applyJwtAuthModule } from './jwt-auth.mjs';
 import { applyLoggerModule } from './logger.mjs';
+import { applyRateLimitModule } from './rate-limit.mjs';
 import { applySwaggerModule } from './swagger.mjs';
 
 function ensureForgeonLikeProject(targetRoot) {
@@ -29,6 +30,7 @@ const MODULE_APPLIERS = {
   i18n: applyI18nModule,
   'jwt-auth': applyJwtAuthModule,
   logger: applyLoggerModule,
+  'rate-limit': applyRateLimitModule,
   swagger: applySwaggerModule,
 };
 

package/src/modules/executor.test.mjs

@@ -42,6 +42,45 @@ function assertDbPrismaWiring(projectRoot) {
   assert.match(healthController, /PrismaService/);
 }
 
+function assertRateLimitWiring(projectRoot) {
+  const appModule = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'src', 'app.module.ts'), 'utf8');
+  assert.match(appModule, /rateLimitConfig/);
+  assert.match(appModule, /rateLimitEnvSchema/);
+  assert.match(appModule, /ForgeonRateLimitModule/);
+
+  const apiPackage = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'package.json'), 'utf8');
+  assert.match(apiPackage, /@forgeon\/rate-limit/);
+  assert.match(apiPackage, /pnpm --filter @forgeon\/rate-limit build/);
+
+  const apiDockerfile = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'Dockerfile'), 'utf8');
+  assert.match(apiDockerfile, /COPY packages\/rate-limit\/package\.json packages\/rate-limit\/package\.json/);
+  assert.match(apiDockerfile, /COPY packages\/rate-limit packages\/rate-limit/);
+  assert.match(apiDockerfile, /RUN pnpm --filter @forgeon\/rate-limit build/);
+
+  const compose = fs.readFileSync(path.join(projectRoot, 'infra', 'docker', 'compose.yml'), 'utf8');
+  assert.match(compose, /THROTTLE_ENABLED: \$\{THROTTLE_ENABLED\}/);
+  assert.match(compose, /THROTTLE_LIMIT: \$\{THROTTLE_LIMIT\}/);
+
+  const apiEnv = fs.readFileSync(path.join(projectRoot, 'apps', 'api', '.env.example'), 'utf8');
+  assert.match(apiEnv, /THROTTLE_ENABLED=true/);
+  assert.match(apiEnv, /THROTTLE_TTL=10/);
+  assert.match(apiEnv, /THROTTLE_LIMIT=3/);
+
+  const healthController = fs.readFileSync(
+    path.join(projectRoot, 'apps', 'api', 'src', 'health', 'health.controller.ts'),
+    'utf8',
+  );
+  assert.match(healthController, /@Get\('rate-limit'\)/);
+  assert.match(healthController, /TOO_MANY_REQUESTS/);
+
+  const appTsx = fs.readFileSync(path.join(projectRoot, 'apps', 'web', 'src', 'App.tsx'), 'utf8');
+  assert.match(appTsx, /Check rate limit \(click repeatedly\)/);
+  assert.match(appTsx, /Rate limit probe response/);
+
+  const readme = fs.readFileSync(path.join(projectRoot, 'README.md'), 'utf8');
+  assert.match(readme, /## Rate Limit Module/);
+}
+
 function assertJwtAuthWiring(projectRoot, withPrismaStore) {
   const apiPackage = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'package.json'), 'utf8');
   assert.match(apiPackage, /@forgeon\/auth-api/);
@@ -529,6 +568,41 @@ describe('addModule', () => {
     }
   });
 
+  it('applies rate-limit module on top of scaffold without i18n', () => {
+    const targetRoot = mkTmp('forgeon-module-rate-limit-');
+    const projectRoot = path.join(targetRoot, 'demo-rate-limit');
+    const templateRoot = path.join(packageRoot, 'templates', 'base');
+
+    try {
+      scaffoldProject({
+        templateRoot,
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-rate-limit',
+        frontend: 'react',
+        db: 'prisma',
+        dbPrismaEnabled: false,
+        i18nEnabled: false,
+        proxy: 'caddy',
+      });
+
+      const result = addModule({
+        moduleId: 'rate-limit',
+        targetRoot: projectRoot,
+        packageRoot,
+      });
+
+      assert.equal(result.applied, true);
+      assertRateLimitWiring(projectRoot);
+
+      const moduleDoc = fs.readFileSync(result.docsPath, 'utf8');
+      assert.match(moduleDoc, /## Idea \/ Why/);
+      assert.match(moduleDoc, /## Configuration/);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+
   it('applies swagger module on top of scaffold without i18n', () => {
     const targetRoot = mkTmp('forgeon-module-swagger-');
     const projectRoot = path.join(targetRoot, 'demo-swagger');
@@ -1144,6 +1218,43 @@ describe('addModule', () => {
     }
   });
 
+  it('keeps rate-limit wiring valid after mixed module installation order', () => {
+    const targetRoot = mkTmp('forgeon-module-rate-limit-order-');
+    const projectRoot = path.join(targetRoot, 'demo-rate-limit-order');
+    const templateRoot = path.join(packageRoot, 'templates', 'base');
+
+    try {
+      scaffoldProject({
+        templateRoot,
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-rate-limit-order',
+        frontend: 'react',
+        db: 'prisma',
+        dbPrismaEnabled: false,
+        i18nEnabled: false,
+        proxy: 'caddy',
+      });
+
+      for (const moduleId of ['jwt-auth', 'logger', 'swagger', 'rate-limit', 'i18n', 'db-prisma']) {
+        addModule({ moduleId, targetRoot: projectRoot, packageRoot });
+      }
+
+      assertRateLimitWiring(projectRoot);
+
+      const healthController = fs.readFileSync(
+        path.join(projectRoot, 'apps', 'api', 'src', 'health', 'health.controller.ts'),
+        'utf8',
+      );
+      const classStart = healthController.indexOf('export class HealthController {');
+      const classEnd = healthController.lastIndexOf('\n}');
+      const rateLimitProbe = healthController.indexOf("@Get('rate-limit')");
+      assert.equal(rateLimitProbe > classStart && rateLimitProbe < classEnd, true);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+
   it('keeps db-prisma wiring across module installation orders', () => {
     const sequences = [
       ['logger', 'swagger', 'i18n'],

package/src/modules/i18n.mjs

@@ -405,7 +405,108 @@ function patchRootPackage(targetRoot) {
   writeJson(packagePath, packageJson);
 }
 
+function restoreKnownWebProbes(targetRoot, previousAppContent) {
+  if (!previousAppContent) {
+    return;
+  }
+
+  const filePath = path.join(targetRoot, 'apps', 'web', 'src', 'App.tsx');
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+
+  const ensureProbeState = (stateLine) => {
+    if (content.includes(stateLine)) {
+      return;
+    }
+    const anchors = [
+      '  const [rateLimitProbeResult, setRateLimitProbeResult] = useState<ProbeResult | null>(null);',
+      '  const [authProbeResult, setAuthProbeResult] = useState<ProbeResult | null>(null);',
+      '  const [dbProbeResult, setDbProbeResult] = useState<ProbeResult | null>(null);',
+      '  const [validationProbeResult, setValidationProbeResult] = useState<ProbeResult | null>(null);',
+    ];
+    const anchor = anchors.find((line) => content.includes(line));
+    if (anchor) {
+      content = ensureLineAfter(content, anchor, stateLine);
+    }
+  };
+
+  const ensureProbeButton = (buttonText, buttonCode) => {
+    if (content.includes(buttonText)) {
+      return;
+    }
+    const actionsStart = content.indexOf('<div className="actions">');
+    if (actionsStart < 0) {
+      return;
+    }
+    const actionsEnd = content.indexOf('\n      </div>', actionsStart);
+    if (actionsEnd < 0) {
+      return;
+    }
+    content = `${content.slice(0, actionsEnd)}\n${buttonCode}${content.slice(actionsEnd)}`;
+  };
+
+  const ensureProbeResult = (resultLine) => {
+    if (content.includes(resultLine)) {
+      return;
+    }
+    const networkLine = '      {networkError ? <p className="error">{networkError}</p> : null}';
+    if (content.includes(networkLine)) {
+      content = content.replace(networkLine, `${resultLine}\n${networkLine}`);
+      return;
+    }
+    const anchors = [
+      "      {renderResult('Rate limit probe response', rateLimitProbeResult)}",
+      "      {renderResult('Auth probe response', authProbeResult)}",
+      "      {renderResult('DB probe response', dbProbeResult)}",
+      "      {renderResult('Validation probe response', validationProbeResult)}",
+    ];
+    const anchor = anchors.find((line) => content.includes(line));
+    if (anchor) {
+      content = ensureLineAfter(content, anchor, resultLine);
+    }
+  };
+
+  if (previousAppContent.includes('Check database (create user)')) {
+    ensureProbeState('  const [dbProbeResult, setDbProbeResult] = useState<ProbeResult | null>(null);');
+    ensureProbeButton(
+      'Check database (create user)',
+      "        <button onClick={() => runProbe(setDbProbeResult, '/health/db', { method: 'POST' })}>\n          Check database (create user)\n        </button>",
+    );
+    ensureProbeResult("      {renderResult('DB probe response', dbProbeResult)}");
+  }
+
+  if (previousAppContent.includes('Check JWT auth probe')) {
+    ensureProbeState('  const [authProbeResult, setAuthProbeResult] = useState<ProbeResult | null>(null);');
+    ensureProbeButton(
+      'Check JWT auth probe',
+      "        <button onClick={() => runProbe(setAuthProbeResult, '/health/auth')}>Check JWT auth probe</button>",
+    );
+    ensureProbeResult("      {renderResult('Auth probe response', authProbeResult)}");
+  }
+
+  if (previousAppContent.includes('Check rate limit (click repeatedly)')) {
+    ensureProbeState(
+      '  const [rateLimitProbeResult, setRateLimitProbeResult] = useState<ProbeResult | null>(null);',
+    );
+    ensureProbeButton(
+      'Check rate limit (click repeatedly)',
+      "        <button onClick={() => runProbe(setRateLimitProbeResult, '/health/rate-limit')}>\n          Check rate limit (click repeatedly)\n        </button>",
+    );
+    ensureProbeResult("      {renderResult('Rate limit probe response', rateLimitProbeResult)}");
+  }
+
+  fs.writeFileSync(filePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
 export function applyI18nModule({ packageRoot, targetRoot }) {
+  const existingWebAppPath = path.join(targetRoot, 'apps', 'web', 'src', 'App.tsx');
+  const previousAppContent = fs.existsSync(existingWebAppPath)
+    ? fs.readFileSync(existingWebAppPath, 'utf8')
+    : '';
+
   copyFromBase(packageRoot, targetRoot, path.join('scripts', 'i18n-add.mjs'));
   copyFromBase(packageRoot, targetRoot, path.join('packages', 'i18n'));
   copyFromBase(packageRoot, targetRoot, path.join('resources', 'i18n'));
@@ -415,6 +516,7 @@ export function applyI18nModule({ packageRoot, targetRoot }) {
   copyFromPreset(packageRoot, targetRoot, path.join('apps', 'web', 'src', 'App.tsx'));
   copyFromPreset(packageRoot, targetRoot, path.join('apps', 'web', 'src', 'i18n.ts'));
   copyFromPreset(packageRoot, targetRoot, path.join('apps', 'web', 'src', 'main.tsx'));
+  restoreKnownWebProbes(targetRoot, previousAppContent);
 
   patchI18nPackage(targetRoot);
   patchApiPackage(targetRoot);

package/src/modules/rate-limit.mjs

@@ -0,0 +1,346 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { copyRecursive, writeJson } from '../utils/fs.mjs';
+import {
+  ensureBuildSteps,
+  ensureClassMember,
+  ensureDependency,
+  ensureImportLine,
+  ensureLineAfter,
+  ensureLineBefore,
+  ensureLoadItem,
+  ensureValidatorSchema,
+  upsertEnvLines,
+} from './shared/patch-utils.mjs';
+
+function copyFromPreset(packageRoot, targetRoot, relativePath) {
+  const source = path.join(packageRoot, 'templates', 'module-presets', 'rate-limit', relativePath);
+  if (!fs.existsSync(source)) {
+    throw new Error(`Missing rate-limit preset template: ${source}`);
+  }
+  const destination = path.join(targetRoot, relativePath);
+  copyRecursive(source, destination);
+}
+
+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'));
+  ensureDependency(packageJson, '@forgeon/rate-limit', 'workspace:*');
+  ensureBuildSteps(packageJson, 'predev', ['pnpm --filter @forgeon/rate-limit build']);
+  writeJson(packagePath, packageJson);
+}
+
+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');
+  if (!content.includes("from '@forgeon/rate-limit';")) {
+    if (content.includes("import { ForgeonI18nModule, i18nConfig, i18nEnvSchema } from '@forgeon/i18n';")) {
+      content = ensureLineAfter(
+        content,
+        "import { ForgeonI18nModule, i18nConfig, i18nEnvSchema } from '@forgeon/i18n';",
+        "import { ForgeonRateLimitModule, rateLimitConfig, rateLimitEnvSchema } from '@forgeon/rate-limit';",
+      );
+    } else if (
+      content.includes("import { authConfig, authEnvSchema, ForgeonAuthModule } from '@forgeon/auth-api';")
+    ) {
+      content = ensureLineAfter(
+        content,
+        "import { authConfig, authEnvSchema, ForgeonAuthModule } from '@forgeon/auth-api';",
+        "import { ForgeonRateLimitModule, rateLimitConfig, rateLimitEnvSchema } from '@forgeon/rate-limit';",
+      );
+    } else if (
+      content.includes("import { ForgeonLoggerModule, loggerConfig, loggerEnvSchema } from '@forgeon/logger';")
+    ) {
+      content = ensureLineAfter(
+        content,
+        "import { ForgeonLoggerModule, loggerConfig, loggerEnvSchema } from '@forgeon/logger';",
+        "import { ForgeonRateLimitModule, rateLimitConfig, rateLimitEnvSchema } from '@forgeon/rate-limit';",
+      );
+    } else if (
+      content.includes("import { ForgeonSwaggerModule, swaggerConfig, swaggerEnvSchema } from '@forgeon/swagger';")
+    ) {
+      content = ensureLineAfter(
+        content,
+        "import { ForgeonSwaggerModule, swaggerConfig, swaggerEnvSchema } from '@forgeon/swagger';",
+        "import { ForgeonRateLimitModule, rateLimitConfig, rateLimitEnvSchema } from '@forgeon/rate-limit';",
+      );
+    } else if (
+      content.includes("import { dbPrismaConfig, dbPrismaEnvSchema, DbPrismaModule } from '@forgeon/db-prisma';")
+    ) {
+      content = ensureLineAfter(
+        content,
+        "import { dbPrismaConfig, dbPrismaEnvSchema, DbPrismaModule } from '@forgeon/db-prisma';",
+        "import { ForgeonRateLimitModule, rateLimitConfig, rateLimitEnvSchema } from '@forgeon/rate-limit';",
+      );
+    } else {
+      content = ensureLineAfter(
+        content,
+        "import { ConfigModule } from '@nestjs/config';",
+        "import { ForgeonRateLimitModule, rateLimitConfig, rateLimitEnvSchema } from '@forgeon/rate-limit';",
+      );
+    }
+  }
+
+  content = ensureLoadItem(content, 'rateLimitConfig');
+  content = ensureValidatorSchema(content, 'rateLimitEnvSchema');
+
+  if (!content.includes('    ForgeonRateLimitModule,')) {
+    if (content.includes('    ForgeonI18nModule.register({')) {
+      content = ensureLineBefore(content, '    ForgeonI18nModule.register({', '    ForgeonRateLimitModule,');
+    } else if (content.includes('    ForgeonAuthModule.register({')) {
+      content = ensureLineBefore(content, '    ForgeonAuthModule.register({', '    ForgeonRateLimitModule,');
+    } else if (content.includes('    ForgeonAuthModule.register(),')) {
+      content = ensureLineBefore(content, '    ForgeonAuthModule.register(),', '    ForgeonRateLimitModule,');
+    } else if (content.includes('    DbPrismaModule,')) {
+      content = ensureLineAfter(content, '    DbPrismaModule,', '    ForgeonRateLimitModule,');
+    } else if (content.includes('    ForgeonLoggerModule,')) {
+      content = ensureLineAfter(content, '    ForgeonLoggerModule,', '    ForgeonRateLimitModule,');
+    } else if (content.includes('    ForgeonSwaggerModule,')) {
+      content = ensureLineAfter(content, '    ForgeonSwaggerModule,', '    ForgeonRateLimitModule,');
+    } else {
+      content = ensureLineAfter(content, '    CoreErrorsModule,', '    ForgeonRateLimitModule,');
+    }
+  }
+
+  fs.writeFileSync(filePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function patchHealthController(targetRoot) {
+  const filePath = path.join(targetRoot, 'apps', 'api', 'src', 'health', 'health.controller.ts');
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+  if (!content.includes("@Get('rate-limit')")) {
+    const method = `
+  @Get('rate-limit')
+  getRateLimitProbe() {
+    return {
+      status: 'ok',
+      feature: 'rate-limit',
+      hint: 'Repeat this request quickly to trigger TOO_MANY_REQUESTS.',
+    };
+  }
+`;
+    content = ensureClassMember(content, 'HealthController', method, { beforeNeedle: 'private translate(' });
+  }
+
+  fs.writeFileSync(filePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function patchWebApp(targetRoot) {
+  const filePath = path.join(targetRoot, 'apps', 'web', 'src', 'App.tsx');
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+  content = content
+    .replace(/^\s*\{\/\* forgeon:probes:actions:start \*\/\}\r?\n?/gm, '')
+    .replace(/^\s*\{\/\* forgeon:probes:actions:end \*\/\}\r?\n?/gm, '')
+    .replace(/^\s*\{\/\* forgeon:probes:results:start \*\/\}\r?\n?/gm, '')
+    .replace(/^\s*\{\/\* forgeon:probes:results:end \*\/\}\r?\n?/gm, '');
+
+  if (!content.includes('rateLimitProbeResult')) {
+    const stateAnchors = [
+      '  const [dbProbeResult, setDbProbeResult] = useState<ProbeResult | null>(null);',
+      '  const [authProbeResult, setAuthProbeResult] = useState<ProbeResult | null>(null);',
+      '  const [validationProbeResult, setValidationProbeResult] = useState<ProbeResult | null>(null);',
+    ];
+    const stateAnchor = stateAnchors.find((line) => content.includes(line));
+    if (stateAnchor) {
+      content = ensureLineAfter(
+        content,
+        stateAnchor,
+        '  const [rateLimitProbeResult, setRateLimitProbeResult] = useState<ProbeResult | null>(null);',
+      );
+    }
+  }
+
+  if (!content.includes('Check rate limit (click repeatedly)')) {
+    const probePath = content.includes("runProbe(setHealthResult, '/health')")
+      ? '/health/rate-limit'
+      : '/api/health/rate-limit';
+    const button = `        <button onClick={() => runProbe(setRateLimitProbeResult, '${probePath}')}>\n          Check rate limit (click repeatedly)\n        </button>`;
+
+    const actionsStart = content.indexOf('<div className="actions">');
+    if (actionsStart >= 0) {
+      const actionsEnd = content.indexOf('\n      </div>', actionsStart);
+      if (actionsEnd >= 0) {
+        content = `${content.slice(0, actionsEnd)}\n${button}${content.slice(actionsEnd)}`;
+      }
+    }
+  }
+
+  if (!content.includes("{renderResult('Rate limit probe response', rateLimitProbeResult)}")) {
+    const resultLine = "      {renderResult('Rate limit probe response', rateLimitProbeResult)}";
+    const networkLine = '      {networkError ? <p className="error">{networkError}</p> : null}';
+    if (content.includes(networkLine)) {
+      content = content.replace(networkLine, `${resultLine}\n${networkLine}`);
+    } else {
+      const anchors = [
+        "{renderResult('Auth probe response', authProbeResult)}",
+        "{renderResult('DB probe response', dbProbeResult)}",
+        "{renderResult('Validation probe response', validationProbeResult)}",
+      ];
+      const anchor = anchors.find((line) => content.includes(line));
+      if (anchor) {
+        content = ensureLineAfter(content, anchor, resultLine);
+      }
+    }
+  }
+
+  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');
+  const packageAnchors = [
+    'COPY packages/auth-api/package.json packages/auth-api/package.json',
+    'COPY packages/logger/package.json packages/logger/package.json',
+    'COPY packages/swagger/package.json packages/swagger/package.json',
+    'COPY packages/i18n/package.json packages/i18n/package.json',
+    'COPY packages/db-prisma/package.json packages/db-prisma/package.json',
+    'COPY packages/core/package.json packages/core/package.json',
+  ];
+  const packageAnchor = packageAnchors.find((line) => content.includes(line)) ?? packageAnchors.at(-1);
+  content = ensureLineAfter(
+    content,
+    packageAnchor,
+    'COPY packages/rate-limit/package.json packages/rate-limit/package.json',
+  );
+
+  const sourceAnchors = [
+    'COPY packages/auth-api packages/auth-api',
+    'COPY packages/logger packages/logger',
+    'COPY packages/swagger packages/swagger',
+    'COPY packages/i18n packages/i18n',
+    'COPY packages/db-prisma packages/db-prisma',
+    'COPY packages/core packages/core',
+  ];
+  const sourceAnchor = sourceAnchors.find((line) => content.includes(line)) ?? sourceAnchors.at(-1);
+  content = ensureLineAfter(content, sourceAnchor, 'COPY packages/rate-limit packages/rate-limit');
+
+  content = content.replace(/^RUN pnpm --filter @forgeon\/rate-limit build\r?\n?/gm, '');
+  const buildAnchor = content.includes('RUN pnpm --filter @forgeon/api prisma:generate')
+    ? 'RUN pnpm --filter @forgeon/api prisma:generate'
+    : 'RUN pnpm --filter @forgeon/api build';
+  content = ensureLineBefore(content, buildAnchor, 'RUN pnpm --filter @forgeon/rate-limit 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('THROTTLE_ENABLED: ${THROTTLE_ENABLED}')) {
+    const anchors = [
+      /^(\s+AUTH_DEMO_PASSWORD:.*)$/m,
+      /^(\s+JWT_ACCESS_SECRET:.*)$/m,
+      /^(\s+LOGGER_LEVEL:.*)$/m,
+      /^(\s+SWAGGER_ENABLED:.*)$/m,
+      /^(\s+I18N_DEFAULT_LANG:.*)$/m,
+      /^(\s+DATABASE_URL:.*)$/m,
+      /^(\s+API_PREFIX:.*)$/m,
+    ];
+    const anchorPattern = anchors.find((pattern) => pattern.test(content)) ?? anchors.at(-1);
+    content = content.replace(
+      anchorPattern,
+      `$1
+      THROTTLE_ENABLED: \${THROTTLE_ENABLED}
+      THROTTLE_TTL: \${THROTTLE_TTL}
+      THROTTLE_LIMIT: \${THROTTLE_LIMIT}
+      THROTTLE_TRUST_PROXY: \${THROTTLE_TRUST_PROXY}`,
+    );
+  }
+
+  fs.writeFileSync(composePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function patchReadme(targetRoot) {
+  const readmePath = path.join(targetRoot, 'README.md');
+  if (!fs.existsSync(readmePath)) {
+    return;
+  }
+
+  const marker = '## Rate Limit Module';
+  let content = fs.readFileSync(readmePath, 'utf8').replace(/\r\n/g, '\n');
+  if (content.includes(marker)) {
+    return;
+  }
+
+  const section = `## Rate Limit Module
+
+The rate-limit add-module provides a simple first-line safeguard against burst traffic, accidental request loops, and brute-force style abuse.
+
+What it adds:
+- global request throttling for the API
+- proxy-aware trust configuration for Caddy/Nginx setups
+- a probe endpoint: \`GET /api/health/rate-limit\`
+- a frontend probe button to verify the 429 response path
+
+How to verify:
+1. click "Check rate limit (click repeatedly)" several times within a few seconds
+2. the first requests return \`200\`
+3. the next request returns a \`429 TOO_MANY_REQUESTS\` envelope
+
+Configuration (env):
+- \`THROTTLE_ENABLED=true\`
+- \`THROTTLE_TTL=10\` (seconds)
+- \`THROTTLE_LIMIT=3\`
+- \`THROTTLE_TRUST_PROXY=false\`
+
+Operational notes:
+- \`THROTTLE_TRUST_PROXY=true\` is recommended behind reverse proxies
+- this is an in-memory throttle preset, not a distributed limiter`;
+
+  if (content.includes('## Prisma In Docker Start')) {
+    content = content.replace('## Prisma In Docker Start', `${section}\n\n## Prisma In Docker Start`);
+  } else {
+    content = `${content.trimEnd()}\n\n${section}\n`;
+  }
+
+  fs.writeFileSync(readmePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+export function applyRateLimitModule({ packageRoot, targetRoot }) {
+  copyFromPreset(packageRoot, targetRoot, path.join('packages', 'rate-limit'));
+  patchApiPackage(targetRoot);
+  patchAppModule(targetRoot);
+  patchHealthController(targetRoot);
+  patchWebApp(targetRoot);
+  patchApiDockerfile(targetRoot);
+  patchCompose(targetRoot);
+  patchReadme(targetRoot);
+
+  upsertEnvLines(path.join(targetRoot, 'apps', 'api', '.env.example'), [
+    'THROTTLE_ENABLED=true',
+    'THROTTLE_TTL=10',
+    'THROTTLE_LIMIT=3',
+    'THROTTLE_TRUST_PROXY=false',
+  ]);
+  upsertEnvLines(path.join(targetRoot, 'infra', 'docker', '.env.example'), [
+    'THROTTLE_ENABLED=true',
+    'THROTTLE_TTL=10',
+    'THROTTLE_LIMIT=3',
+    'THROTTLE_TRUST_PROXY=false',
+  ]);
+}

package/src/modules/registry.mjs

@@ -39,9 +39,27 @@ const MODULE_PRESETS = {
     description: 'JWT auth preset with contracts/api module split, guard+strategy, and DB-aware refresh token storage wiring.',
     docFragments: ['00_title', '10_overview', '20_scope', '90_status_implemented'],
   },
-  queue: {
-    id: 'queue',
-    label: 'Queue Worker',
+  'rate-limit': {
+    id: 'rate-limit',
+    label: 'Rate Limit',
+    category: 'auth-security',
+    implemented: true,
+    description: 'Request throttling preset with env-based limits, proxy-aware trust, and a runtime probe endpoint.',
+    docFragments: [
+      '00_title',
+      '10_overview',
+      '20_idea',
+      '30_what_it_adds',
+      '40_how_it_works',
+      '50_how_to_use',
+      '60_configuration',
+      '70_operational_notes',
+      '90_status_implemented',
+    ],
+  },
+  queue: {
+    id: 'queue',
+    label: 'Queue Worker',
     category: 'background-jobs',
     implemented: false,
     description: 'Queue processing preset (BullMQ-style app wiring).',

package/src/run-add-module.mjs

@@ -7,14 +7,81 @@ import { addModule } from './modules/executor.mjs';
 import { listModulePresets } from './modules/registry.mjs';
 import { printModuleAdded, runIntegrationFlow } from './integrations/flow.mjs';
 import { writeJson } from './utils/fs.mjs';
-
+
 function printModuleList() {
   const modules = listModulePresets();
   console.log('Available modules:');
   for (const moduleItem of modules) {
     const status = moduleItem.implemented ? 'implemented' : 'planned';
     console.log(`- ${moduleItem.id} (${status}) - ${moduleItem.description}`);
-  }
+  }
+}
+
+function toSortedObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return {};
+  }
+
+  return Object.fromEntries(
+    Object.entries(value).sort(([left], [right]) => left.localeCompare(right)),
+  );
+}
+
+function collectDependencyManifestState(targetRoot) {
+  const state = new Map();
+  if (!fs.existsSync(targetRoot)) {
+    return state;
+  }
+
+  const queue = [targetRoot];
+  const skipDirs = new Set(['node_modules', '.git', 'dist', 'build']);
+
+  while (queue.length > 0) {
+    const currentDir = queue.shift();
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (!skipDirs.has(entry.name)) {
+          queue.push(path.join(currentDir, entry.name));
+        }
+        continue;
+      }
+
+      if (!entry.isFile() || entry.name !== 'package.json') {
+        continue;
+      }
+
+      const filePath = path.join(currentDir, entry.name);
+      const packageJson = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      const snapshot = {
+        name: packageJson.name ?? null,
+        dependencies: toSortedObject(packageJson.dependencies),
+        devDependencies: toSortedObject(packageJson.devDependencies),
+        optionalDependencies: toSortedObject(packageJson.optionalDependencies),
+        peerDependencies: toSortedObject(packageJson.peerDependencies),
+        onlyBuiltDependencies: Array.isArray(packageJson.pnpm?.onlyBuiltDependencies)
+          ? [...packageJson.pnpm.onlyBuiltDependencies].sort()
+          : [],
+      };
+
+      state.set(path.relative(targetRoot, filePath), JSON.stringify(snapshot));
+    }
+  }
+
+  return state;
+}
+
+function getChangedDependencyManifestPaths(beforeState, afterState) {
+  const changed = [];
+
+  for (const [filePath, nextSnapshot] of afterState.entries()) {
+    if (beforeState.get(filePath) !== nextSnapshot) {
+      changed.push(filePath);
+    }
+  }
+
+  return changed.sort();
 }
 
 function ensureSyncTooling({ packageRoot, targetRoot }) {
@@ -64,10 +131,11 @@ export async function runAddModule(argv = process.argv.slice(2)) {
     throw new Error('Module id is required. Use `create-forgeon add --list` to see available modules.');
   }
 
-  const srcDir = path.dirname(fileURLToPath(import.meta.url));
-  const packageRoot = path.resolve(srcDir, '..');
-  const targetRoot = path.resolve(process.cwd(), options.project);
-
+  const srcDir = path.dirname(fileURLToPath(import.meta.url));
+  const packageRoot = path.resolve(srcDir, '..');
+  const targetRoot = path.resolve(process.cwd(), options.project);
+  const dependencyManifestStateBefore = collectDependencyManifestState(targetRoot);
+
   const result = addModule({
     moduleId: options.moduleId,
     targetRoot,
@@ -80,4 +148,13 @@ export async function runAddModule(argv = process.argv.slice(2)) {
     packageRoot,
     relatedModuleId: result.preset.id,
   });
+
+  const dependencyManifestStateAfter = collectDependencyManifestState(targetRoot);
+  const changedDependencyManifestPaths = getChangedDependencyManifestPaths(
+    dependencyManifestStateBefore,
+    dependencyManifestStateAfter,
+  );
+  if (changedDependencyManifestPaths.length > 0) {
+    console.log('Next: run pnpm install');
+  }
 }

package/templates/base/README.md

@@ -37,9 +37,9 @@ pnpm forgeon:sync-integrations
 ```
 
 Current sync coverage:
-- `jwt-auth + swagger`: adds OpenAPI decorators for auth controller/DTOs.
+- `jwt-auth + db-prisma`: wires persistent refresh-token storage for auth.
 
-`create-forgeon add <module>` also runs integration sync automatically (best effort).
+`create-forgeon add <module>` scans for relevant integration groups and can apply them immediately.
 
 ## i18n Configuration
 

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

@@ -63,6 +63,7 @@ Must contain:
 - Contracts package can be imported from both sides without circular dependencies.
 - Contracts package exports are stable from `dist/index` entrypoint.
 - Module has docs under `docs/AI/MODULES/<module-id>.md`.
+- Module docs must explain: why it exists, what it adds, how it works, how to use it, how to configure it, and current operational limits.
 - 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/module-fragments/rate-limit/00_title.md

@@ -0,0 +1 @@
+# {{MODULE_LABEL}}

package/templates/module-fragments/rate-limit/10_overview.md

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

package/templates/module-fragments/rate-limit/20_idea.md

@@ -0,0 +1,11 @@
+## Idea / Why
+
+This module adds a simple first-line request throttle to the API.
+
+It exists to reduce three common classes of problems:
+
+1. burst traffic from accidental frontend loops
+2. low-cost abuse against public endpoints
+3. brute-force style retries against auth endpoints
+
+It is intentionally small and predictable. The goal is not to replace a WAF, CDN, or distributed rate limiter. The goal is to give every Forgeon project a safe baseline that can be installed in one step.

package/templates/module-fragments/rate-limit/30_what_it_adds.md

@@ -0,0 +1,10 @@
+## What It Adds
+
+- `@forgeon/rate-limit` workspace package
+- env-backed throttle configuration
+- global Nest throttler guard wiring
+- reverse-proxy trust toggle for Caddy / Nginx deployments
+- `GET /api/health/rate-limit` probe endpoint
+- frontend probe button on the generated home page
+
+This module is API-first. It does not add shared contracts or a web package in v1 because the runtime value is in backend request throttling, not in reusable client-side types.

package/templates/module-fragments/rate-limit/40_how_it_works.md

@@ -0,0 +1,13 @@
+## How It Works
+
+Implementation details:
+
+- `RateLimitConfigService` reads `THROTTLE_*` env values through `@nestjs/config`.
+- `ForgeonRateLimitModule` registers `ThrottlerModule` globally.
+- A global guard applies the throttle rules to incoming HTTP requests.
+- When `THROTTLE_TRUST_PROXY=true`, the module enables Express `trust proxy` through the active HTTP adapter so client IPs are resolved correctly behind reverse proxies.
+
+Error behavior:
+
+- throttled requests return HTTP `429`
+- the existing Forgeon error envelope wraps the response as `TOO_MANY_REQUESTS`

package/templates/module-fragments/rate-limit/50_how_to_use.md

@@ -0,0 +1,21 @@
+## How To Use
+
+Install:
+
+```bash
+npx create-forgeon@latest add rate-limit
+pnpm install
+```
+
+Verify:
+
+1. start the project
+2. open the generated frontend
+3. click `Check rate limit (click repeatedly)` multiple times within the throttle window
+4. observe the transition from `200` to `429`
+
+You can also hit the probe route directly:
+
+```bash
+GET /api/health/rate-limit
+```

package/templates/module-fragments/rate-limit/60_configuration.md

@@ -0,0 +1,15 @@
+## Configuration
+
+Environment keys:
+
+- `THROTTLE_ENABLED=true`
+- `THROTTLE_TTL=10`
+- `THROTTLE_LIMIT=3`
+- `THROTTLE_TRUST_PROXY=false`
+
+Meaning:
+
+- `THROTTLE_ENABLED`: hard on/off switch
+- `THROTTLE_TTL`: throttle window in seconds
+- `THROTTLE_LIMIT`: maximum requests allowed inside that window
+- `THROTTLE_TRUST_PROXY`: use forwarded client IPs when behind Caddy / Nginx

package/templates/module-fragments/rate-limit/70_operational_notes.md

@@ -0,0 +1,10 @@
+## Operational Notes
+
+Current scope:
+
+- in-memory throttling only
+- one global baseline policy
+- no Redis / distributed storage
+- no route-specific policy DSL in v1
+
+That means this module is appropriate for local development, simple deployments, and as a base preset. If a project later needs distributed throttling or different policies per route or user, this module should be extended rather than replaced blindly.

package/templates/module-fragments/rate-limit/90_status_implemented.md

@@ -0,0 +1,3 @@
+## Status
+
+Implemented in the current scaffold.

package/templates/module-presets/rate-limit/packages/rate-limit/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@forgeon/rate-limit",
+  "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",
+    "@nestjs/core": "^11.0.1",
+    "@nestjs/throttler": "^6.4.0",
+    "rxjs": "^7.8.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "^5.7.3"
+  }
+}

package/templates/module-presets/rate-limit/packages/rate-limit/src/forgeon-rate-limit.module.ts

@@ -0,0 +1,50 @@
+import { Module, OnModuleInit } from '@nestjs/common';
+import { APP_GUARD, HttpAdapterHost } from '@nestjs/core';
+import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
+import { RateLimitConfigModule } from './rate-limit-config.module';
+import { RateLimitConfigService } from './rate-limit-config.service';
+
+@Module({
+  imports: [
+    RateLimitConfigModule,
+    ThrottlerModule.forRootAsync({
+      imports: [RateLimitConfigModule],
+      inject: [RateLimitConfigService],
+      useFactory: (config: RateLimitConfigService) => ({
+        errorMessage: 'Too many requests. Please try again later.',
+        skipIf: () => !config.enabled,
+        throttlers: [
+          {
+            ttl: config.ttlMs,
+            limit: config.limit,
+          },
+        ],
+      }),
+    }),
+  ],
+  providers: [
+    {
+      provide: APP_GUARD,
+      useClass: ThrottlerGuard,
+    },
+  ],
+  exports: [RateLimitConfigModule],
+})
+export class ForgeonRateLimitModule implements OnModuleInit {
+  constructor(
+    private readonly rateLimitConfig: RateLimitConfigService,
+    private readonly httpAdapterHost: HttpAdapterHost,
+  ) {}
+
+  onModuleInit(): void {
+    if (!this.rateLimitConfig.trustProxy) {
+      return;
+    }
+
+    const adapter = this.httpAdapterHost.httpAdapter;
+    const instance = adapter?.getInstance?.();
+    if (instance && typeof instance.set === 'function') {
+      instance.set('trust proxy', true);
+    }
+  }
+}

package/templates/module-presets/rate-limit/packages/rate-limit/src/index.ts

@@ -0,0 +1,5 @@
+export * from './forgeon-rate-limit.module';
+export * from './rate-limit-config.loader';
+export * from './rate-limit-config.module';
+export * from './rate-limit-config.service';
+export * from './rate-limit-env.schema';

package/templates/module-presets/rate-limit/packages/rate-limit/src/rate-limit-config.loader.ts

@@ -0,0 +1,25 @@
+import { registerAs } from '@nestjs/config';
+import { parseRateLimitEnv } from './rate-limit-env.schema';
+
+export const RATE_LIMIT_CONFIG_NAMESPACE = 'rateLimit';
+
+export interface RateLimitConfigValues {
+  enabled: boolean;
+  ttlSeconds: number;
+  limit: number;
+  trustProxy: boolean;
+}
+
+export const rateLimitConfig = registerAs(
+  RATE_LIMIT_CONFIG_NAMESPACE,
+  (): RateLimitConfigValues => {
+    const env = parseRateLimitEnv(process.env);
+
+    return {
+      enabled: env.THROTTLE_ENABLED,
+      ttlSeconds: env.THROTTLE_TTL,
+      limit: env.THROTTLE_LIMIT,
+      trustProxy: env.THROTTLE_TRUST_PROXY,
+    };
+  },
+);

package/templates/module-presets/rate-limit/packages/rate-limit/src/rate-limit-config.module.ts

@@ -0,0 +1,8 @@
+import { Module } from '@nestjs/common';
+import { RateLimitConfigService } from './rate-limit-config.service';
+
+@Module({
+  providers: [RateLimitConfigService],
+  exports: [RateLimitConfigService],
+})
+export class RateLimitConfigModule {}

package/templates/module-presets/rate-limit/packages/rate-limit/src/rate-limit-config.service.ts

@@ -0,0 +1,35 @@
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import {
+  RATE_LIMIT_CONFIG_NAMESPACE,
+  RateLimitConfigValues,
+} from './rate-limit-config.loader';
+
+@Injectable()
+export class RateLimitConfigService {
+  constructor(private readonly configService: ConfigService) {}
+
+  get enabled(): boolean {
+    return this.configService.getOrThrow<boolean>(`${RATE_LIMIT_CONFIG_NAMESPACE}.enabled`);
+  }
+
+  get ttlSeconds(): RateLimitConfigValues['ttlSeconds'] {
+    return this.configService.getOrThrow<RateLimitConfigValues['ttlSeconds']>(
+      `${RATE_LIMIT_CONFIG_NAMESPACE}.ttlSeconds`,
+    );
+  }
+
+  get ttlMs(): number {
+    return this.ttlSeconds * 1000;
+  }
+
+  get limit(): RateLimitConfigValues['limit'] {
+    return this.configService.getOrThrow<RateLimitConfigValues['limit']>(
+      `${RATE_LIMIT_CONFIG_NAMESPACE}.limit`,
+    );
+  }
+
+  get trustProxy(): boolean {
+    return this.configService.getOrThrow<boolean>(`${RATE_LIMIT_CONFIG_NAMESPACE}.trustProxy`);
+  }
+}

package/templates/module-presets/rate-limit/packages/rate-limit/src/rate-limit-env.schema.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+
+export const rateLimitEnvSchema = z
+  .object({
+    THROTTLE_ENABLED: z.coerce.boolean().default(true),
+    THROTTLE_TTL: z.coerce.number().int().positive().default(10),
+    THROTTLE_LIMIT: z.coerce.number().int().positive().default(3),
+    THROTTLE_TRUST_PROXY: z.coerce.boolean().default(false),
+  })
+  .passthrough();
+
+export type RateLimitEnv = z.infer<typeof rateLimitEnvSchema>;
+
+export function parseRateLimitEnv(input: Record<string, unknown>): RateLimitEnv {
+  return rateLimitEnvSchema.parse(input);
+}

package/templates/module-presets/rate-limit/packages/rate-limit/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}