create-forgeon 0.3.24 → 0.3.26

package/package.json

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

package/src/modules/accounts-communications.mjs

@@ -0,0 +1,146 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { copyRecursive, writeJson } from '../utils/fs.mjs';
+import {
+  ensureBuildSteps,
+  ensureDependency,
+  ensureImportLine,
+  ensureLineAfter,
+  ensureLineBefore,
+} from './shared/patch-utils.mjs';
+
+function copyFromPreset(packageRoot, targetRoot, relativePath) {
+  const source = path.join(packageRoot, 'templates', 'module-presets', 'accounts-communications', relativePath);
+  if (!fs.existsSync(source)) {
+    throw new Error(`Missing accounts-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/accounts-communications', 'workspace:*');
+  ensureBuildSteps(packageJson, 'predev', ['pnpm --filter @forgeon/accounts-communications 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');
+  content = ensureImportLine(
+    content,
+    "import { AuthCommunicationsController, AuthCommunicationsService, ConfirmedChangePasswordHandler, PendingVerificationRegisterHandler } from '@forgeon/accounts-communications';",
+  );
+
+  const accountsModuleLine = `    ForgeonAccountsModule.register({
+      users: UsersModule.register({}),
+      controllers: [AuthCommunicationsController],
+      providers: [
+        AuthCommunicationsService,
+        PendingVerificationRegisterHandler,
+        ConfirmedChangePasswordHandler,
+      ],
+      handlers: {
+        register: PendingVerificationRegisterHandler,
+        changePassword: ConfirmedChangePasswordHandler,
+      },
+    }),`;
+
+  if (content.includes('    ForgeonAccountsModule.register({')) {
+    content = content.replace(
+      / {4}ForgeonAccountsModule\.register\([\s\S]*? {4}\}\),/m,
+      accountsModuleLine,
+    );
+  }
+
+  fs.writeFileSync(filePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function patchApiDockerfile(targetRoot) {
+  const dockerfilePath = path.join(targetRoot, 'apps', 'api', 'Dockerfile');
+  if (!fs.existsSync(dockerfilePath)) {
+    return;
+  }
+
+  let content = fs.readFileSync(dockerfilePath, 'utf8').replace(/\r\n/g, '\n');
+  content = ensureLineAfter(
+    content,
+    'COPY packages/accounts-api/package.json packages/accounts-api/package.json',
+    'COPY packages/accounts-communications/package.json packages/accounts-communications/package.json',
+  );
+  content = ensureLineAfter(
+    content,
+    'COPY packages/accounts-api packages/accounts-api',
+    'COPY packages/accounts-communications packages/accounts-communications',
+  );
+
+  content = content.replace(/^RUN pnpm --filter @forgeon\/accounts-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/accounts-communications build');
+
+  fs.writeFileSync(dockerfilePath, `${content.trimEnd()}\n`, 'utf8');
+}
+
+function patchReadme(targetRoot) {
+  const readmePath = path.join(targetRoot, 'README.md');
+  if (!fs.existsSync(readmePath)) {
+    return;
+  }
+
+  const section = [
+    '## Accounts Communications Module',
+    '',
+    'The accounts-communications add-module extends the base accounts runtime with communications-backed auth/account flows.',
+    '',
+    'What it adds:',
+    '- `@forgeon/accounts-communications` extension runtime for messaging-based auth/account operations',
+    '- pending-verification registration mode',
+    '- confirmable password changes and password reset flows',
+    '- email change confirmation routes under the same `/api/auth/*` namespace',
+    '',
+    'Current boundaries:',
+    '- requires both `accounts` and `communications`',
+    '- rebinds `register` and `change-password` handler implementations through the accounts composition point',
+    '- keeps base account state and pending-operation records inside `accounts`',
+  ].join('\n');
+
+  let content = fs.readFileSync(readmePath, 'utf8').replace(/\r\n/g, '\n');
+  const sectionHeading = '## Accounts 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 applyAccountsCommunicationsModule({ packageRoot, targetRoot }) {
+  copyFromPreset(packageRoot, targetRoot, path.join('packages', 'accounts-communications'));
+  patchApiPackage(targetRoot);
+  patchAppModule(targetRoot);
+  patchApiDockerfile(targetRoot);
+  patchReadme(targetRoot);
+}

package/src/modules/accounts.mjs

@@ -57,10 +57,11 @@ function patchPrismaSchema(targetRoot) {
   }
 
   let content = fs.readFileSync(schemaPath, 'utf8').replace(/\r\n/g, '\n');
-  const userModel = `model User {
+const userModel = `model User {
   id               String             @id @default(cuid())
   status           String             @default("active")
   data             Json?
+  emailVerifiedAt  DateTime?
   createdAt        DateTime           @default(now())
   updatedAt        DateTime           @updatedAt
   deletedAt        DateTime?
@@ -69,6 +70,7 @@ function patchPrismaSchema(targetRoot) {
   authIdentities   AuthIdentity[]
   authCredential   AuthCredential?
   authRefreshTokens AuthRefreshToken[]
+  authPendingOperations AuthPendingOperation[]
 }`;
 
   if (/model User \{[\s\S]*?\n\}/m.test(content)) {
@@ -119,6 +121,19 @@ function patchPrismaSchema(targetRoot) {
   user       User     @relation(fields: [userId], references: [id], onDelete: Cascade)
 
   @@index([userId, createdAt])
+}`,
+    `model AuthPendingOperation {
+  id         String   @id @default(cuid())
+  userId     String
+  type       String
+  tokenHash  String
+  metadata   Json?
+  expiresAt  DateTime
+  consumedAt DateTime?
+  createdAt  DateTime @default(now())
+  user       User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+
+  @@index([userId, type, createdAt])
 }`,
   ];
 
@@ -336,7 +351,7 @@ function patchReadme(targetRoot) {
     '',
     'Current boundaries:',
     '- `UsersModule.register({ user, profile, settings })` controls runtime defaults for JSON-backed extension fields',
-    '- email verification and password-reset request flows send best-effort communication intents through `CommunicationsService`',
+    '- base accounts runtime works without `communications`; delivery-assisted auth/account flows belong to the optional `accounts-communications` extension',
     '- base accounts schema does not include RBAC storage',
     ACCOUNTS_RBAC_MARKERS.start,
     ACCOUNTS_DEFAULT_RBAC_BLOCK,
@@ -349,9 +364,6 @@ function patchReadme(targetRoot) {
     '- `POST /api/auth/logout`',
     '- `GET /api/auth/me`',
     '- `POST /api/auth/change-password`',
-    '- `POST /api/auth/verify-email` (stub)',
-    '- `POST /api/auth/password-reset/request` (stub)',
-    '- `POST /api/auth/password-reset/confirm` (stub)',
   ].join('\n');
 
   let content = fs.readFileSync(readmePath, 'utf8').replace(/\r\n/g, '\n');

package/src/modules/communications.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 {
@@ -165,6 +165,7 @@ function patchReadme(targetRoot) {
     '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');
@@ -203,7 +204,7 @@ export function applyCommunicationsModule({ packageRoot, 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_FROM=',
     'COMMUNICATIONS_EMAIL_REPLY_TO=',
     'COMMUNICATIONS_EMAIL_SUBJECT_PREFIX=[Forgeon]',
     'COMMUNICATIONS_EMAIL_SMTP_HOST=smtp.gmail.com',
@@ -218,7 +219,7 @@ export function applyCommunicationsModule({ packageRoot, targetRoot }) {
   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_FROM=',
     'COMMUNICATIONS_EMAIL_REPLY_TO=',
     'COMMUNICATIONS_EMAIL_SUBJECT_PREFIX=[Forgeon]',
     'COMMUNICATIONS_EMAIL_SMTP_HOST=smtp.gmail.com',

package/src/modules/dependencies.test.mjs

@@ -41,7 +41,7 @@ const TEST_PRESETS = [
     implemented: true,
     detectionPaths: ['packages/accounts-api/package.json'],
     provides: ['accounts-runtime'],
-    requires: [{ type: 'capability', id: 'db-adapter' }, { type: 'capability', id: 'communications-runtime' }],
+    requires: [{ type: 'capability', id: 'db-adapter' }],
     optionalIntegrations: [
       {
         id: 'accounts-rbac',
@@ -56,6 +56,15 @@ const TEST_PRESETS = [
       },
     ],
   },
+  {
+    id: 'accounts-communications',
+    label: 'Accounts Communications',
+    implemented: true,
+    detectionPaths: ['packages/accounts-communications/package.json'],
+    provides: ['accounts-communications-runtime'],
+    requires: [{ type: 'module', id: 'accounts' }, { type: 'module', id: 'communications' }],
+    optionalIntegrations: [],
+  },
   {
     id: 'rbac',
     label: 'RBAC',
@@ -119,7 +128,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: [],
   },
   {
@@ -128,7 +137,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: [],
   },
   {
@@ -137,7 +146,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: [],
   },
   {
@@ -213,10 +222,9 @@ describe('module dependency helpers', () => {
       });
 
       assert.equal(result.cancelled, false);
-      assert.deepEqual(result.moduleSequence, ['db-prisma', 'communications', 'accounts']);
+      assert.deepEqual(result.moduleSequence, ['db-prisma', 'accounts']);
       assert.deepEqual(result.selectedProviders, {
         'db-adapter': 'db-prisma',
-        'communications-runtime': 'communications',
       });
     } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
@@ -269,7 +277,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 {
@@ -289,14 +297,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 {
@@ -316,14 +323,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 {
@@ -343,7 +349,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 });
@@ -387,6 +392,7 @@ describe('module dependency helpers', () => {
         'db-prisma',
         'communications',
         'accounts',
+        'accounts-communications',
         'rbac',
         'files-local',
         'files',
@@ -399,8 +405,6 @@ 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',
       });
       assert.equal(result.rootModuleIds.includes('files-s3'), false);
@@ -451,6 +455,25 @@ describe('module dependency helpers', () => {
     }
   });
 
+  it('builds a concrete install plan for accounts-communications with required parent modules', async () => {
+    const targetRoot = mkTmp('forgeon-deps-accounts-comms-');
+
+    try {
+      const result = await resolveModuleInstallPlan({
+        moduleId: 'accounts-communications',
+        targetRoot,
+        presets: TEST_PRESETS,
+        withRequired: true,
+        isInteractive: false,
+      });
+
+      assert.equal(result.cancelled, false);
+      assert.deepEqual(result.moduleSequence, ['db-prisma', 'accounts', 'communications', 'accounts-communications']);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+
   it('keeps the requested module in the plan even when it is already installed', async () => {
     const targetRoot = mkTmp('forgeon-deps-reapply-');
 

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 { applyAccountsCommunicationsModule } from './accounts-communications.mjs';
 import { applyCommunicationsModule } from './communications.mjs';
 import { applyLoggerModule } from './logger.mjs';
 import { applyRateLimitModule } from './rate-limit.mjs';
@@ -45,6 +46,7 @@ const MODULE_APPLIERS = {
   'files-s3': applyFilesS3Module,
   i18n: applyI18nModule,
   accounts: applyAccountsModule,
+  'accounts-communications': applyAccountsCommunicationsModule,
   communications: applyCommunicationsModule,
   logger: applyLoggerModule,
   queue: applyQueueModule,

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';
@@ -793,16 +793,17 @@ function assertAccountsWiring(projectRoot) {
   assert.match(compose, /JWT_REFRESH_SECRET: \$\{JWT_REFRESH_SECRET\}/);
   assert.match(compose, /AUTH_ARGON2_MEMORY_COST: \$\{AUTH_ARGON2_MEMORY_COST\}/);
 
-  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, /CommunicationsService/);
+  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, /works without `communications`/);
 
-  const authServiceSource = fs.readFileSync(
-    path.join(projectRoot, 'packages', 'accounts-api', 'src', 'auth.service.ts'),
-    'utf8',
-  );
-  assert.match(authServiceSource, /import type \{ RegisterRequest \} from '@forgeon\/accounts-contracts';/);
+  const authServiceSource = fs.readFileSync(
+    path.join(projectRoot, 'packages', 'accounts-api', 'src', 'auth.service.ts'),
+    'utf8',
+  );
+  assert.match(authServiceSource, /RegisterRequest/);
+  assert.match(authServiceSource, /REGISTER_HANDLER/);
 
   const authCoreSource = fs.readFileSync(
     path.join(projectRoot, 'packages', 'accounts-api', 'src', 'auth-core.service.ts'),
@@ -811,12 +812,12 @@ function assertAccountsWiring(projectRoot) {
   assert.match(authCoreSource, /AuthStore/);
   assert.doesNotMatch(authCoreSource, /ACCOUNTS_PERSISTENCE_PORT/);
 
-  const accountsApiPackage = fs.readFileSync(
-    path.join(projectRoot, 'packages', 'accounts-api', 'package.json'),
-    'utf8',
-  );
+  const accountsApiPackage = fs.readFileSync(
+    path.join(projectRoot, 'packages', 'accounts-api', 'package.json'),
+    'utf8',
+  );
   assert.match(accountsApiPackage, /@forgeon\/db-prisma/);
-  assert.match(accountsApiPackage, /@forgeon\/communications/);
+  assert.doesNotMatch(accountsApiPackage, /@forgeon\/communications/);
 
   const authStoreSource = fs.readFileSync(
     path.join(projectRoot, 'packages', 'accounts-api', 'src', 'auth.store.ts'),
@@ -2228,6 +2229,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');
@@ -2281,7 +2365,7 @@ describe('addModule', () => {
 
       const readme = fs.readFileSync(path.join(projectRoot, 'README.md'), 'utf8');
       assert.match(readme, /POST \/api\/auth\/register/);
-      assert.match(readme, /POST \/api\/auth\/password-reset\/request/);
+      assert.doesNotMatch(readme, /POST \/api\/auth\/password-reset\/request/);
       assert.match(readme, /\/api\/users\/:id\/settings/);
 
       const moduleDoc = fs.readFileSync(result.docsPath, 'utf8');
@@ -2706,6 +2790,11 @@ 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'],
   },
@@ -158,10 +158,10 @@ const MODULE_PRESETS = {
     category: 'auth-security',
     implemented: true,
     description:
-      'Accounts umbrella module with DB-backed users/auth runtime, argon2 passwords, JWT access+refresh rotation, owner-scoped self-service routes, and communications integration.',
+      'Accounts umbrella module with standalone DB-backed users/auth runtime, argon2 passwords, JWT access+refresh rotation, owner-scoped self-service routes, and handler-based extension seams.',
     detectionPaths: ['packages/accounts-api/package.json'],
     provides: ['accounts-runtime'],
-    requires: [{ type: 'capability', id: 'db-adapter' }, { type: 'capability', id: 'communications-runtime' }],
+    requires: [{ type: 'capability', id: 'db-adapter' }],
     optionalIntegrations: [
       {
         id: 'accounts-rbac',
@@ -180,6 +180,22 @@ const MODULE_PRESETS = {
     ],
     docFragments: ['00_title', '10_overview', '20_scope', '90_status_implemented'],
   },
+  'accounts-communications': {
+    id: 'accounts-communications',
+    label: 'Accounts Communications',
+    category: 'auth-security',
+    implemented: true,
+    description:
+      'Optional bridge module that extends accounts with communications-backed registration verification, password reset, password change confirmation, and email change confirmation flows.',
+    detectionPaths: ['packages/accounts-communications/package.json'],
+    provides: ['accounts-communications-runtime'],
+    requires: [
+      { type: 'module', id: 'accounts' },
+      { type: 'module', id: 'communications' },
+    ],
+    optionalIntegrations: [],
+    docFragments: ['00_title', '10_overview', '20_scope', '90_status_implemented'],
+  },
   'rate-limit': {
     id: 'rate-limit',
     label: 'Rate Limit',