create-forgeon 0.3.22 → 0.3.24

package/README.md

@@ -1,4 +1,4 @@
-# create-forgeon
+# create-forgeon
 
 CLI package for generating Forgeon fullstack monorepo projects.
 
@@ -9,19 +9,20 @@ CLI package for generating Forgeon fullstack monorepo projects.
 > ![warning](https://img.shields.io/badge/STATUS-PRE--RELEASE%20DO%20NOT%20USE-red)
 
 ## Usage
-
+
 ```bash
 npx create-forgeon@latest my-app --i18n true --db-prisma true --proxy caddy
 npx create-forgeon@latest my-app --db-prisma false --proxy caddy
 ```
-
-If flags are omitted, the CLI asks interactive questions.
-Project name stays text input; fixed-choice prompts use arrow-key selection (`Up/Down + Enter`).
-
+
+If flags are omitted, the CLI asks interactive questions.
+Project name stays text input; fixed-choice prompts use arrow-key selection (`Up/Down + Enter`).
+
 ```bash
 npx create-forgeon@latest add --list
 npx create-forgeon@latest add i18n --project ./my-app
-npx create-forgeon@latest add jwt-auth --project ./my-app
+npx create-forgeon@latest add communications --project ./my-app
+npx create-forgeon@latest add accounts --project ./my-app --with-required
 npx create-forgeon@latest add files --with-required --provider db-adapter=db-prisma
 ```
 
@@ -29,16 +30,17 @@ npx create-forgeon@latest add files --with-required --provider db-adapter=db-pri
 cd my-app
 pnpm forgeon:sync-integrations
 ```
-
-## Notes
-
+
+## Notes
+
 - Canonical runtime stack is fixed: NestJS + React + Docker.
 - DB is module-driven: `db-prisma` is default-on and can be disabled at scaffold time.
 - Reverse proxy options: `caddy` (default), `nginx`, `none`.
 - `add i18n` is implemented and applies backend/frontend i18n wiring.
-- `add jwt-auth` is implemented and auto-detects DB adapter support for refresh-token persistence.
+- `add communications` is implemented and adds the shared email/sms/push orchestration surface.
+- `add accounts` is implemented and installs the DB-backed accounts/authentication runtime.
 - Integration sync is bundled by default and runs after `add` commands (best-effort).
 - Module notes are written under `modules/<module-id>/README.md`.
 - Hard prerequisites are explicit:
   - TTY mode prompts for provider resolution and install plan confirmation
-  - non-TTY mode can use `--with-required` plus `--provider <capability>=<module>`
+  - non-TTY mode can use `--with-required` plus `--provider <capability>=<module>`

package/package.json

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

package/src/modules/accounts.mjs

@@ -336,7 +336,7 @@ function patchReadme(targetRoot) {
     '',
     'Current boundaries:',
     '- `UsersModule.register({ user, profile, settings })` controls runtime defaults for JSON-backed extension fields',
-    '- email verification and password reset use an internal email stub through `AccountsEmailPort`',
+    '- email verification and password-reset request flows send best-effort communication intents through `CommunicationsService`',
     '- base accounts schema does not include RBAC storage',
     ACCOUNTS_RBAC_MARKERS.start,
     ACCOUNTS_DEFAULT_RBAC_BLOCK,
@@ -420,3 +420,5 @@ export function applyAccountsModule({ packageRoot, targetRoot }) {
 
 
 
+
+

package/src/modules/communications.mjs

@@ -0,0 +1,232 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { copyRecursive, writeJson } from '../utils/fs.mjs';
+import {
+  ensureBuildSteps,
+  ensureDependency,
+  ensureLineAfter,
+  ensureLineBefore,
+  upsertEnvLines,
+} from './shared/patch-utils.mjs';
+import { patchAppModuleRegistration } from './shared/nest-runtime-wiring.mjs';
+import { ensureWebProbeDefinition, resolveProbeTargets } from './shared/probes.mjs';
+
+function copyFromPreset(packageRoot, targetRoot, relativePath) {
+  const source = path.join(packageRoot, 'templates', 'module-presets', 'communications', relativePath);
+  if (!fs.existsSync(source)) {
+    throw new Error(`Missing communications preset template: ${source}`);
+  }
+  const destination = path.join(targetRoot, relativePath);
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  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/communications', 'workspace:*');
+  ensureBuildSteps(packageJson, 'predev', ['pnpm --filter @forgeon/communications build']);
+  writeJson(packagePath, packageJson);
+}
+
+function patchAppModule(targetRoot) {
+  patchAppModuleRegistration(targetRoot, {
+    importLine: "import { communicationsConfig, communicationsEnvSchema, ForgeonCommunicationsModule } from '@forgeon/communications';",
+    loadItem: 'communicationsConfig',
+    envSchema: 'communicationsEnvSchema',
+    moduleLine: '    ForgeonCommunicationsModule.register(),',
+    afterAnchors: ['    DbPrismaModule,', '    ForgeonLoggerModule,'],
+    fallbackAnchor: '    CoreErrorsModule,',
+  });
+}
+
+function registerWebProbe(targetRoot) {
+  const probeTargets = resolveProbeTargets({ targetRoot, moduleId: 'communications' });
+  ensureWebProbeDefinition({
+    targetRoot,
+    probeTargets,
+    definition: {
+      id: 'communications',
+      title: 'Communications',
+      buttonLabel: 'Send communications probe email',
+      resultTitle: 'Communications probe response',
+      path: '/health/communications',
+      request: {
+        method: 'POST',
+        body: {
+          email: '$INPUT.email$',
+        },
+      },
+      inputs: [
+        {
+          id: 'email',
+          label: 'Test email',
+          type: 'email',
+          placeholder: 'you@example.com',
+          defaultValue: 'probe@example.com',
+        },
+      ],
+    },
+  });
+}
+
+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/accounts-api/package.json packages/accounts-api/package.json',
+    'COPY packages/logger/package.json packages/logger/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/communications/package.json packages/communications/package.json');
+
+  const sourceAnchors = [
+    'COPY packages/accounts-api packages/accounts-api',
+    'COPY packages/logger packages/logger',
+    '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/communications packages/communications');
+
+  content = content.replace(/^RUN pnpm --filter @forgeon\/communications 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/communications 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('COMMUNICATIONS_EMAIL_PROVIDER: ${COMMUNICATIONS_EMAIL_PROVIDER}')) {
+    content = content.replace(
+      /^(\s+API_PREFIX:.*)$/m,
+      `$1
+      COMMUNICATIONS_TEMPLATES_ROOT: \${COMMUNICATIONS_TEMPLATES_ROOT}
+      COMMUNICATIONS_EMAIL_PROVIDER: \${COMMUNICATIONS_EMAIL_PROVIDER}
+      COMMUNICATIONS_EMAIL_FROM: \${COMMUNICATIONS_EMAIL_FROM}
+      COMMUNICATIONS_EMAIL_REPLY_TO: \${COMMUNICATIONS_EMAIL_REPLY_TO}
+      COMMUNICATIONS_EMAIL_SUBJECT_PREFIX: \${COMMUNICATIONS_EMAIL_SUBJECT_PREFIX}
+      COMMUNICATIONS_EMAIL_SMTP_HOST: \${COMMUNICATIONS_EMAIL_SMTP_HOST}
+      COMMUNICATIONS_EMAIL_SMTP_PORT: \${COMMUNICATIONS_EMAIL_SMTP_PORT}
+      COMMUNICATIONS_EMAIL_SMTP_SECURE: \${COMMUNICATIONS_EMAIL_SMTP_SECURE}
+      COMMUNICATIONS_EMAIL_SMTP_USER: \${COMMUNICATIONS_EMAIL_SMTP_USER}
+      COMMUNICATIONS_EMAIL_SMTP_PASS: \${COMMUNICATIONS_EMAIL_SMTP_PASS}
+      COMMUNICATIONS_SMS_PROVIDER: \${COMMUNICATIONS_SMS_PROVIDER}
+      COMMUNICATIONS_PUSH_PROVIDER: \${COMMUNICATIONS_PUSH_PROVIDER}`,
+    );
+  }
+
+  fs.writeFileSync(composePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function patchReadme(targetRoot) {
+  const readmePath = path.join(targetRoot, 'README.md');
+  if (!fs.existsSync(readmePath)) {
+    return;
+  }
+
+  const section = [
+    '## Communications Module',
+    '',
+    'The communications add-module provides a single orchestration surface for email, sms, and push delivery.',
+    '',
+    'What it adds:',
+    '- `@forgeon/communications` backend runtime with file-based template loading and simple placeholder rendering',
+    '- real email delivery through the Gmail SMTP transport configuration',
+    '- SMS and PUSH stub channels for future expansion',
+    '- probe routes: `GET /api/health/communications` and `POST /api/health/communications`',
+    '- generated resources under `resources/communications/email`, `resources/communications/sms`, and `resources/communications/push`',
+    '',
+    'Current boundaries:',
+    '- domain modules should inject only `CommunicationsService`',
+    '- provider selection is module-owned configuration, never a runtime input field',
+    '- queues, scheduling, delivery history, and retries are intentionally out of scope for v1',
+    '',
+    'Example env keys:',
+    '- `COMMUNICATIONS_EMAIL_PROVIDER=gmail-smtp`',
+    '- `COMMUNICATIONS_EMAIL_SMTP_HOST=smtp.gmail.com`',
+    '- `COMMUNICATIONS_EMAIL_SMTP_USER=`',
+    '- `COMMUNICATIONS_EMAIL_SMTP_PASS=`',
+  ].join('\n');
+
+  let content = fs.readFileSync(readmePath, 'utf8').replace(/\r\n/g, '\n');
+  const sectionHeading = '## Communications Module';
+  if (content.includes(sectionHeading)) {
+    const start = content.indexOf(sectionHeading);
+    const tail = content.slice(start + sectionHeading.length);
+    const nextHeadingMatch = tail.match(/\n##\s+/);
+    const end =
+      nextHeadingMatch && nextHeadingMatch.index !== undefined
+        ? start + sectionHeading.length + nextHeadingMatch.index + 1
+        : content.length;
+    content = `${content.slice(0, start)}${section}\n\n${content.slice(end).replace(/^\n+/, '')}`;
+  } else 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 applyCommunicationsModule({ packageRoot, targetRoot }) {
+  copyFromPreset(packageRoot, targetRoot, path.join('packages', 'communications'));
+  copyFromPreset(packageRoot, targetRoot, path.join('resources', 'communications'));
+
+  patchApiPackage(targetRoot);
+  patchAppModule(targetRoot);
+  registerWebProbe(targetRoot);
+  patchApiDockerfile(targetRoot);
+  patchCompose(targetRoot);
+  patchReadme(targetRoot);
+
+  upsertEnvLines(path.join(targetRoot, 'apps', 'api', '.env.example'), [
+    'COMMUNICATIONS_TEMPLATES_ROOT=resources/communications',
+    'COMMUNICATIONS_EMAIL_PROVIDER=gmail-smtp',
+    'COMMUNICATIONS_EMAIL_FROM=Forgeon <no-reply@example.com>',
+    'COMMUNICATIONS_EMAIL_REPLY_TO=',
+    'COMMUNICATIONS_EMAIL_SUBJECT_PREFIX=[Forgeon]',
+    'COMMUNICATIONS_EMAIL_SMTP_HOST=smtp.gmail.com',
+    'COMMUNICATIONS_EMAIL_SMTP_PORT=587',
+    'COMMUNICATIONS_EMAIL_SMTP_SECURE=false',
+    'COMMUNICATIONS_EMAIL_SMTP_USER=',
+    'COMMUNICATIONS_EMAIL_SMTP_PASS=',
+    'COMMUNICATIONS_SMS_PROVIDER=stub',
+    'COMMUNICATIONS_PUSH_PROVIDER=stub',
+  ]);
+
+  upsertEnvLines(path.join(targetRoot, 'infra', 'docker', '.env.example'), [
+    'COMMUNICATIONS_TEMPLATES_ROOT=resources/communications',
+    'COMMUNICATIONS_EMAIL_PROVIDER=gmail-smtp',
+    'COMMUNICATIONS_EMAIL_FROM=Forgeon <no-reply@example.com>',
+    'COMMUNICATIONS_EMAIL_REPLY_TO=',
+    'COMMUNICATIONS_EMAIL_SUBJECT_PREFIX=[Forgeon]',
+    'COMMUNICATIONS_EMAIL_SMTP_HOST=smtp.gmail.com',
+    'COMMUNICATIONS_EMAIL_SMTP_PORT=587',
+    'COMMUNICATIONS_EMAIL_SMTP_SECURE=false',
+    'COMMUNICATIONS_EMAIL_SMTP_USER=',
+    'COMMUNICATIONS_EMAIL_SMTP_PASS=',
+    'COMMUNICATIONS_SMS_PROVIDER=stub',
+    'COMMUNICATIONS_PUSH_PROVIDER=stub',
+  ]);
+}

package/src/modules/dependencies.test.mjs

@@ -26,13 +26,22 @@ const TEST_PRESETS = [
     requires: [],
     optionalIntegrations: [],
   },
+  {
+    id: 'communications',
+    label: 'Communications',
+    implemented: true,
+    detectionPaths: ['packages/communications/package.json'],
+    provides: ['communications-runtime'],
+    requires: [],
+    optionalIntegrations: [],
+  },
   {
     id: 'accounts',
     label: 'Accounts',
     implemented: true,
     detectionPaths: ['packages/accounts-api/package.json'],
     provides: ['accounts-runtime'],
-    requires: [{ type: 'capability', id: 'db-adapter' }],
+    requires: [{ type: 'capability', id: 'db-adapter' }, { type: 'capability', id: 'communications-runtime' }],
     optionalIntegrations: [
       {
         id: 'accounts-rbac',
@@ -204,9 +213,10 @@ describe('module dependency helpers', () => {
       });
 
       assert.equal(result.cancelled, false);
-      assert.deepEqual(result.moduleSequence, ['db-prisma', 'accounts']);
+      assert.deepEqual(result.moduleSequence, ['db-prisma', 'communications', 'accounts']);
       assert.deepEqual(result.selectedProviders, {
         'db-adapter': 'db-prisma',
+        'communications-runtime': 'communications',
       });
     } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
@@ -375,6 +385,7 @@ describe('module dependency helpers', () => {
       assert.equal(result.cancelled, false);
       assert.deepEqual(result.moduleSequence, [
         'db-prisma',
+        'communications',
         'accounts',
         'rbac',
         'files-local',
@@ -388,6 +399,7 @@ describe('module dependency helpers', () => {
       assert.deepEqual(result.selectedProviders, {
         'files-storage-adapter': 'files-local',
         'db-adapter': 'db-prisma',
+        'communications-runtime': 'communications',
         'files-runtime': 'files',
         'queue-runtime': 'queue',
       });
@@ -499,3 +511,5 @@ describe('module dependency helpers', () => {
     }
   });
 });
+
+

package/src/modules/executor.mjs

@@ -11,6 +11,7 @@ import { applyFilesLocalModule } from './files-local.mjs';
 import { applyFilesS3Module } from './files-s3.mjs';
 import { applyI18nModule } from './i18n.mjs';
 import { applyAccountsModule } from './accounts.mjs';
+import { applyCommunicationsModule } from './communications.mjs';
 import { applyLoggerModule } from './logger.mjs';
 import { applyRateLimitModule } from './rate-limit.mjs';
 import { applyRbacModule } from './rbac.mjs';
@@ -44,6 +45,7 @@ const MODULE_APPLIERS = {
   'files-s3': applyFilesS3Module,
   i18n: applyI18nModule,
   accounts: applyAccountsModule,
+  communications: applyCommunicationsModule,
   logger: applyLoggerModule,
   queue: applyQueueModule,
   'rate-limit': applyRateLimitModule,
@@ -86,3 +88,5 @@ export function addModule({ moduleId, targetRoot, packageRoot, writeDocs = true
 }
 
 
+
+

package/src/modules/executor.test.mjs

@@ -506,6 +506,16 @@ function assertFilesAccessWiring(projectRoot) {
   assert.match(filesController, /@Req\(\) req: any/);
   assert.match(filesController, /openDownload\(publicId,\s*variant\)/);
 
+  const filesModule = fs.readFileSync(
+    path.join(projectRoot, 'packages', 'files', 'src', 'forgeon-files.module.ts'),
+    'utf8',
+  );
+  assert.match(filesModule, /import \{ ForgeonFilesAccessModule \} from '@forgeon\/files-access';/);
+  assert.match(
+    filesModule,
+    /imports: \[FilesConfigModule, ForgeonFilesAccessModule, (?:ForgeonFilesImageModule, )?DbPrismaModule, \.\.\.\(options\.imports \?\? \[\]\)\],/,
+  );
+
   const healthController = fs.readFileSync(
     path.join(projectRoot, 'apps', 'api', 'src', 'health', 'health.controller.ts'),
     'utf8',
@@ -532,14 +542,14 @@ function assertFilesQuotasWiring(projectRoot) {
   assert.match(appModule, /filesQuotasEnvSchema/);
   assert.match(appModule, /ForgeonFilesQuotasModule/);
 
-  const apiPackage = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'package.json'), 'utf8');
-  assert.match(apiPackage, /@forgeon\/files-quotas/);
-  assert.match(apiPackage, /pnpm --filter @forgeon\/files-quotas build/);
-  assert.equal(
-    apiPackage.indexOf('pnpm --filter @forgeon/files-quotas build') >
-      apiPackage.indexOf('pnpm --filter @forgeon/files build'),
-    true,
-  );
+  const apiPackage = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'package.json'), 'utf8');
+  assert.match(apiPackage, /@forgeon\/files-quotas/);
+  assert.match(apiPackage, /pnpm --filter @forgeon\/files-quotas build/);
+  assert.equal(
+    apiPackage.indexOf('pnpm --filter @forgeon/files-quotas build') >
+      apiPackage.indexOf('pnpm --filter @forgeon/files build'),
+    true,
+  );
 
   const filesPackage = fs.readFileSync(path.join(projectRoot, 'packages', 'files', 'package.json'), 'utf8');
   assert.doesNotMatch(filesPackage, /@forgeon\/files-quotas/);
@@ -550,13 +560,13 @@ function assertFilesQuotasWiring(projectRoot) {
     apiDockerfile,
     /COPY packages\/files-quotas\/package\.json packages\/files-quotas\/package\.json/,
   );
-  assert.match(apiDockerfile, /COPY packages\/files-quotas packages\/files-quotas/);
-  assert.match(apiDockerfile, /RUN pnpm --filter @forgeon\/files-quotas build/);
-  assert.equal(
-    apiDockerfile.indexOf('RUN pnpm --filter @forgeon/files-quotas build') >
-      apiDockerfile.indexOf('RUN pnpm --filter @forgeon/files build'),
-    true,
-  );
+  assert.match(apiDockerfile, /COPY packages\/files-quotas packages\/files-quotas/);
+  assert.match(apiDockerfile, /RUN pnpm --filter @forgeon\/files-quotas build/);
+  assert.equal(
+    apiDockerfile.indexOf('RUN pnpm --filter @forgeon/files-quotas build') >
+      apiDockerfile.indexOf('RUN pnpm --filter @forgeon/files build'),
+    true,
+  );
 
   const filesController = fs.readFileSync(
     path.join(projectRoot, 'packages', 'files', 'src', 'files.controller.ts'),
@@ -591,6 +601,22 @@ function assertFilesQuotasWiring(projectRoot) {
   const readme = fs.readFileSync(path.join(projectRoot, 'README.md'), 'utf8');
   assert.match(readme, /## Files Quotas Module/);
   assert.match(readme, /owner-based limits/i);
+
+  const filesQuotasService = fs.readFileSync(
+    path.join(projectRoot, 'packages', 'files-quotas', 'src', 'files-quotas.service.ts'),
+    'utf8',
+  );
+  assert.match(filesQuotasService, /FilesStore/);
+  assert.match(filesQuotasService, /filesStore\.countOwnerUsage/);
+  assert.doesNotMatch(filesQuotasService, /FilesService/);
+
+  const filesQuotasModule = fs.readFileSync(
+    path.join(projectRoot, 'packages', 'files-quotas', 'src', 'forgeon-files-quotas.module.ts'),
+    'utf8',
+  );
+  assert.match(filesQuotasModule, /DbPrismaModule/);
+  assert.match(filesQuotasModule, /FilesStore/);
+  assert.doesNotMatch(filesQuotasModule, /ForgeonFilesModule/);
 }
 
 function assertFilesImageWiring(projectRoot) {
@@ -611,20 +637,20 @@ function assertFilesImageWiring(projectRoot) {
   const filesPackage = fs.readFileSync(path.join(projectRoot, 'packages', 'files', 'package.json'), 'utf8');
   assert.match(filesPackage, /@forgeon\/files-image/);
 
-  const filesModule = fs.readFileSync(
-    path.join(projectRoot, 'packages', 'files', 'src', 'forgeon-files.module.ts'),
-    'utf8',
-  );
-  assert.match(filesModule, /ForgeonFilesImageModule/);
-  assert.match(
-    filesModule,
-    /imports: \[FilesConfigModule, (?:ForgeonFilesAccessModule, )?ForgeonFilesImageModule, DbPrismaModule, \.\.\.\(options\.imports \?\? \[\]\)\],/,
-  );
-
-  const filesService = fs.readFileSync(
-    path.join(projectRoot, 'packages', 'files', 'src', 'files.service.ts'),
-    'utf8',
-  );
+  const filesModule = fs.readFileSync(
+    path.join(projectRoot, 'packages', 'files', 'src', 'forgeon-files.module.ts'),
+    'utf8',
+  );
+  assert.match(filesModule, /ForgeonFilesImageModule/);
+  assert.match(
+    filesModule,
+    /imports: \[FilesConfigModule, (?:ForgeonFilesAccessModule, )?ForgeonFilesImageModule, DbPrismaModule, \.\.\.\(options\.imports \?\? \[\]\)\],/,
+  );
+
+  const filesService = fs.readFileSync(
+    path.join(projectRoot, 'packages', 'files', 'src', 'files.service.ts'),
+    'utf8',
+  );
   assert.match(filesService, /FilesImageService/);
   assert.match(filesService, /filesImageService\.sanitizeForStorage/);
   assert.match(filesService, /sanitizeForStorage\({/);
@@ -770,7 +796,7 @@ function assertAccountsWiring(projectRoot) {
   const readme = fs.readFileSync(path.join(projectRoot, 'README.md'), 'utf8');
   assert.match(readme, /## Accounts Module/);
   assert.match(readme, /owner-scoped user routes/);
-  assert.match(readme, /AccountsEmailPort/);
+  assert.match(readme, /CommunicationsService/);
 
   const authServiceSource = fs.readFileSync(
     path.join(projectRoot, 'packages', 'accounts-api', 'src', 'auth.service.ts'),
@@ -789,7 +815,8 @@ function assertAccountsWiring(projectRoot) {
     path.join(projectRoot, 'packages', 'accounts-api', 'package.json'),
     'utf8',
   );
-  assert.match(accountsApiPackage, /@forgeon\/db-prisma/);
+  assert.match(accountsApiPackage, /@forgeon\/db-prisma/);
+  assert.match(accountsApiPackage, /@forgeon\/communications/);
 
   const authStoreSource = fs.readFileSync(
     path.join(projectRoot, 'packages', 'accounts-api', 'src', 'auth.store.ts'),
@@ -2681,5 +2708,7 @@ describe('addModule', () => {
 
 
 
+
+
 
 

package/src/modules/files-access.mjs

@@ -1,4 +1,4 @@
-import fs from 'node:fs';
+import fs from 'node:fs';
 import path from 'node:path';
 import { copyRecursive, writeJson } from '../utils/fs.mjs';
 import {
@@ -51,6 +51,29 @@ function patchFilesPackage(targetRoot) {
   writeJson(packagePath, packageJson);
 }
 
+function patchFilesModule(targetRoot) {
+  const filePath = path.join(targetRoot, 'packages', 'files', 'src', 'forgeon-files.module.ts');
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+  content = ensureImportLine(content, "import { ForgeonFilesAccessModule } from '@forgeon/files-access';");
+
+  if (!content.includes('imports: [FilesConfigModule, ForgeonFilesAccessModule,')) {
+    content = content.replace(
+      'imports: [FilesConfigModule, ForgeonFilesImageModule, DbPrismaModule, ...(options.imports ?? [])],',
+      'imports: [FilesConfigModule, ForgeonFilesAccessModule, ForgeonFilesImageModule, DbPrismaModule, ...(options.imports ?? [])],',
+    );
+    content = content.replace(
+      'imports: [FilesConfigModule, DbPrismaModule, ...(options.imports ?? [])],',
+      'imports: [FilesConfigModule, ForgeonFilesAccessModule, DbPrismaModule, ...(options.imports ?? [])],',
+    );
+  }
+
+  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)) {
@@ -366,6 +389,7 @@ export function applyFilesAccessModule({ packageRoot, targetRoot }) {
 
   patchApiPackage(targetRoot);
   patchFilesPackage(targetRoot);
+  patchFilesModule(targetRoot);
   patchAppModule(targetRoot);
   patchFilesController(targetRoot);
   patchHealthController(targetRoot, probeTargets);

package/src/modules/registry.mjs

@@ -139,16 +139,29 @@ const MODULE_PRESETS = {
     optionalIntegrations: [],
     docFragments: ['00_title', '10_overview', '20_scope', '90_status_implemented'],
   },
+  communications: {
+    id: 'communications',
+    label: 'Communications',
+    category: 'platform-communications',
+    implemented: true,
+    description:
+      'Canonical communication orchestration module with file-based templates, Gmail SMTP email delivery, and SMS/PUSH stubs.',
+    detectionPaths: ['packages/communications/package.json'],
+    provides: ['communications-runtime'],
+    requires: [],
+    optionalIntegrations: [],
+    docFragments: ['00_title', '10_overview', '20_scope', '90_status_implemented'],
+  },
   accounts: {
     id: 'accounts',
     label: 'Accounts',
     category: 'auth-security',
     implemented: true,
     description:
-      'Accounts umbrella module with DB-backed users/auth runtime, argon2 passwords, JWT access+refresh rotation, and owner-scoped self-service routes.',
+      'Accounts umbrella module with DB-backed users/auth runtime, argon2 passwords, JWT access+refresh rotation, owner-scoped self-service routes, and communications integration.',
     detectionPaths: ['packages/accounts-api/package.json'],
     provides: ['accounts-runtime'],
-    requires: [{ type: 'capability', id: 'db-adapter' }],
+    requires: [{ type: 'capability', id: 'db-adapter' }, { type: 'capability', id: 'communications-runtime' }],
     optionalIntegrations: [
       {
         id: 'accounts-rbac',
@@ -307,3 +320,6 @@ export function ensureModuleExists(moduleId) {
 
 
 
+
+
+

package/src/modules/shared/probes.mjs

@@ -1,4 +1,4 @@
-import fs from 'node:fs';
+import fs from 'node:fs';
 import path from 'node:path';
 import { readJson } from '../../utils/fs.mjs';
 
@@ -17,6 +17,7 @@ const probeOrders = {
   validation: 30,
   db: 40,
   auth: 50,
+  communications: 55,
   rbac: 60,
   'rate-limit': 70,
   files: 80,
@@ -233,3 +234,4 @@ export function readManagedWebProbeDefinitions(targetRoot) {
 }
 
 
+

package/src/run-add-module.test.mjs

@@ -154,6 +154,7 @@ describe('runAddModule', () => {
         'i18n',
         'logger',
         'swagger',
+        'communications',
         'accounts',
         'rate-limit',
         'rbac',
@@ -228,3 +229,6 @@ describe('runAddModule', () => {
   });
 });
 
+
+
+