create-forgeon 0.3.23 → 0.3.25

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.23",
+  "version": "0.3.25",
   "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,233 @@
+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_FROM=` (falls back to the SMTP user when left empty)',
+    '- `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=',
+    '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=',
+    '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',
@@ -110,7 +119,7 @@ const TEST_PRESETS = [
     implemented: true,
     detectionPaths: ['packages/files-access/package.json'],
     provides: ['files-access-runtime'],
-    requires: [{ type: 'capability', id: 'files-runtime' }],
+    requires: [{ type: 'module', id: 'files' }],
     optionalIntegrations: [],
   },
   {
@@ -119,7 +128,7 @@ const TEST_PRESETS = [
     implemented: true,
     detectionPaths: ['packages/files-quotas/package.json'],
     provides: ['files-quotas-runtime'],
-    requires: [{ type: 'capability', id: 'files-runtime' }],
+    requires: [{ type: 'module', id: 'files' }],
     optionalIntegrations: [],
   },
   {
@@ -128,7 +137,7 @@ const TEST_PRESETS = [
     implemented: true,
     detectionPaths: ['packages/files-image/package.json'],
     provides: ['files-image-runtime'],
-    requires: [{ type: 'capability', id: 'files-runtime' }],
+    requires: [{ type: 'module', id: 'files' }],
     optionalIntegrations: [],
   },
   {
@@ -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 });
@@ -259,7 +269,7 @@ describe('module dependency helpers', () => {
     }
   });
 
-  it('resolves files-access plan through files-runtime capability chain', async () => {
+  it('resolves files-access plan through files core module dependency', async () => {
     const targetRoot = mkTmp('forgeon-deps-files-access-plan-');
 
     try {
@@ -279,14 +289,13 @@ describe('module dependency helpers', () => {
       assert.deepEqual(result.selectedProviders, {
         'db-adapter': 'db-prisma',
         'files-storage-adapter': 'files-local',
-        'files-runtime': 'files',
       });
     } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
     }
   });
 
-  it('resolves files-quotas plan through files-runtime capability chain', async () => {
+  it('resolves files-quotas plan through files core module dependency', async () => {
     const targetRoot = mkTmp('forgeon-deps-files-quotas-plan-');
 
     try {
@@ -306,14 +315,13 @@ describe('module dependency helpers', () => {
       assert.deepEqual(result.selectedProviders, {
         'db-adapter': 'db-prisma',
         'files-storage-adapter': 'files-local',
-        'files-runtime': 'files',
       });
     } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
     }
   });
 
-  it('resolves files-image plan through files-runtime capability chain', async () => {
+  it('resolves files-image plan through files core module dependency', async () => {
     const targetRoot = mkTmp('forgeon-deps-files-image-plan-');
 
     try {
@@ -333,7 +341,6 @@ describe('module dependency helpers', () => {
       assert.deepEqual(result.selectedProviders, {
         'db-adapter': 'db-prisma',
         'files-storage-adapter': 'files-local',
-        'files-runtime': 'files',
       });
     } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
@@ -375,6 +382,7 @@ describe('module dependency helpers', () => {
       assert.equal(result.cancelled, false);
       assert.deepEqual(result.moduleSequence, [
         'db-prisma',
+        'communications',
         'accounts',
         'rbac',
         'files-local',
@@ -388,6 +396,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 +508,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

@@ -1,4 +1,4 @@
-import { describe, it } from 'node:test';
+import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -796,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'),
@@ -816,6 +816,7 @@ function assertAccountsWiring(projectRoot) {
     'utf8',
   );
   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'),
@@ -2227,6 +2228,89 @@ describe('addModule', () => {
     }
   });
 
+  it('applies communications on top of scaffold and wires SMTP-backed probe flow', () => {
+    const targetRoot = mkTmp('forgeon-module-communications-');
+    const projectRoot = path.join(targetRoot, 'demo-communications');
+    const templateRoot = path.join(packageRoot, 'templates', 'base');
+
+    try {
+      scaffoldProject({
+        templateRoot,
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-communications',
+        frontend: 'react',
+        db: 'prisma',
+        dbPrismaEnabled: true,
+        i18nEnabled: true,
+        proxy: 'caddy',
+      });
+
+      const result = addModule({
+        moduleId: 'communications',
+        targetRoot: projectRoot,
+        packageRoot,
+      });
+
+      assert.equal(result.applied, true);
+
+      const appModule = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'src', 'app.module.ts'), 'utf8');
+      assert.match(appModule, /communicationsConfig/);
+      assert.match(appModule, /communicationsEnvSchema/);
+      assert.match(appModule, /ForgeonCommunicationsModule\.register\(\)/);
+
+      const apiPackage = fs.readFileSync(path.join(projectRoot, 'apps', 'api', 'package.json'), 'utf8');
+      assert.match(apiPackage, /@forgeon\/communications/);
+      assert.match(apiPackage, /pnpm --filter @forgeon\/communications build/);
+
+      const communicationsEnv = fs.readFileSync(
+        path.join(projectRoot, 'packages', 'communications', 'src', 'communications-env.schema.ts'),
+        'utf8',
+      );
+      assert.match(communicationsEnv, /normalizeEnvBoolean/);
+      assert.doesNotMatch(communicationsEnv, /COMMUNICATIONS_EMAIL_SMTP_SECURE: z\.coerce\.boolean/);
+
+      const communicationsConfig = fs.readFileSync(
+        path.join(projectRoot, 'packages', 'communications', 'src', 'communications-config.loader.ts'),
+        'utf8',
+      );
+      assert.match(communicationsConfig, /const derivedFrom = env\.COMMUNICATIONS_EMAIL_FROM \|\| env\.COMMUNICATIONS_EMAIL_SMTP_USER/);
+
+      const providerSource = fs.readFileSync(
+        path.join(projectRoot, 'packages', 'communications', 'src', 'email', 'providers', 'gmail-smtp-email.provider.ts'),
+        'utf8',
+      );
+      assert.match(providerSource, /COMMUNICATIONS_EMAIL_PROVIDER_SEND_FAILED/);
+      assert.match(providerSource, /extractErrorDetails/);
+
+      const communicationsModuleSource = fs.readFileSync(
+        path.join(projectRoot, 'packages', 'communications', 'src', 'forgeon-communications.module.ts'),
+        'utf8',
+      );
+      assert.match(communicationsModuleSource, /@Global\(\)/);
+
+      const apiEnv = fs.readFileSync(path.join(projectRoot, 'apps', 'api', '.env.example'), 'utf8');
+      assert.match(apiEnv, /COMMUNICATIONS_EMAIL_SMTP_SECURE=false/);
+      assert.match(apiEnv, /^COMMUNICATIONS_EMAIL_FROM=$/m);
+
+      const dockerEnv = fs.readFileSync(path.join(projectRoot, 'infra', 'docker', '.env.example'), 'utf8');
+      assert.match(dockerEnv, /^COMMUNICATIONS_EMAIL_FROM=$/m);
+
+      const probesTs = readWebProbes(projectRoot);
+      assert.match(probesTs, /"id": "communications"/);
+      assert.match(probesTs, /\$INPUT\.email\$/);
+
+      const readme = fs.readFileSync(path.join(projectRoot, 'README.md'), 'utf8');
+      assert.match(readme, /## Communications Module/);
+      assert.match(readme, /falls back to the SMTP user when left empty/);
+
+      const moduleDoc = fs.readFileSync(result.docsPath, 'utf8');
+      assert.match(moduleDoc, /Status: implemented/);
+      assert.match(moduleDoc, /STARTTLS/);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
   it('applies accounts with db-prisma and wires the DB-backed runtime immediately', () => {
     const targetRoot = mkTmp('forgeon-module-accounts-db-');
     const projectRoot = path.join(targetRoot, 'demo-accounts-db');
@@ -2702,6 +2786,13 @@ describe('addModule', () => {
 
 
 
+
+
+
+
+
+
+
 
 
 

package/src/modules/registry.mjs

@@ -67,10 +67,10 @@ const MODULE_PRESETS = {
     category: 'file-storage',
     implemented: true,
     description:
-      'Resource-level access policy module for files metadata/download/delete operations. Requires files-runtime capability.',
+      'Resource-level access policy extension for the files core module. Requires files.',
     detectionPaths: ['packages/files-access/package.json'],
     provides: ['files-access-runtime'],
-    requires: [{ type: 'capability', id: 'files-runtime' }],
+    requires: [{ type: 'module', id: 'files' }],
     optionalIntegrations: [],
     docFragments: ['00_title', '10_overview', '20_scope', '90_status_implemented'],
   },
@@ -80,10 +80,10 @@ const MODULE_PRESETS = {
     category: 'file-storage',
     implemented: true,
     description:
-      'Owner-level upload quota policy module for files. Requires files-runtime capability.',
+      'Owner-level upload quota extension for the files core module. Requires files.',
     detectionPaths: ['packages/files-quotas/package.json'],
     provides: ['files-quotas-runtime'],
-    requires: [{ type: 'capability', id: 'files-runtime' }],
+    requires: [{ type: 'module', id: 'files' }],
     optionalIntegrations: [],
     docFragments: ['00_title', '10_overview', '20_scope', '90_status_implemented'],
   },
@@ -93,10 +93,10 @@ const MODULE_PRESETS = {
     category: 'file-storage',
     implemented: true,
     description:
-      'Image sanitation module for files runtime (magic-bytes detect + sharp re-encode, metadata stripped by default). Requires files-runtime capability.',
+      'Image sanitation extension for the files core module (magic-bytes detect + sharp re-encode, metadata stripped by default). Requires files.',
     detectionPaths: ['packages/files-image/package.json'],
     provides: ['files-image-runtime'],
-    requires: [{ type: 'capability', id: 'files-runtime' }],
+    requires: [{ type: 'module', id: 'files' }],
     optionalIntegrations: [],
     docFragments: ['00_title', '10_overview', '20_scope', '90_status_implemented'],
   },
@@ -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) {
 
 
 
+
+
+