create-forgeon 0.3.24 → 0.3.25

package/package.json

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

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

@@ -119,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: [],
   },
   {
@@ -128,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: [],
   },
   {
@@ -137,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: [],
   },
   {
@@ -269,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 {
@@ -289,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 {
@@ -316,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 {
@@ -343,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 });

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';
@@ -815,7 +815,7 @@ 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(
@@ -2228,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');
@@ -2706,6 +2789,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'],
   },

package/templates/module-fragments/communications/20_scope.md

@@ -1,4 +1,4 @@
-## Scope
+## Scope
 
 Implemented scope:
 
@@ -14,7 +14,10 @@ Implemented scope:
    - email channel with Gmail SMTP transport configuration
    - sms stub channel
    - push stub channel
-5. Module checks:
+5. SMTP defaults:
+   - `COMMUNICATIONS_EMAIL_SMTP_SECURE=false` uses STARTTLS mode correctly on port `587`
+   - `COMMUNICATIONS_EMAIL_FROM` falls back to the authenticated SMTP user when left empty
+6. Module checks:
    - `GET /api/health/communications`
    - `POST /api/health/communications`
    - default web probe with email input + test send

package/templates/module-presets/accounts/packages/accounts-api/src/forgeon-accounts.module.ts

@@ -1,4 +1,4 @@
-import {
+import {
   DynamicModule,
   Module,
   ModuleMetadata,
@@ -6,7 +6,6 @@ import {
 } from '@nestjs/common';
 import { JwtModule } from '@nestjs/jwt';
 import { PassportModule } from '@nestjs/passport';
-import { ForgeonCommunicationsModule } from '@forgeon/communications';
 import { DbPrismaModule } from '@forgeon/db-prisma';
 import {
   ACCOUNTS_AUTHZ_CLAIMS_RESOLVER,
@@ -41,7 +40,6 @@ export class ForgeonAccountsModule {
       imports: [
         AuthConfigModule,
         DbPrismaModule,
-        ForgeonCommunicationsModule.register(),
         PassportModule.register({ defaultStrategy: 'jwt' }),
         JwtModule.register({}),
         ...(options.imports ?? []),

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

@@ -31,12 +31,13 @@ export const communicationsConfig = registerAs(
   COMMUNICATIONS_CONFIG_NAMESPACE,
   (): CommunicationsConfigValues => {
     const env = parseCommunicationsEnv(process.env as unknown as Record<string, unknown>);
+    const derivedFrom = env.COMMUNICATIONS_EMAIL_FROM || env.COMMUNICATIONS_EMAIL_SMTP_USER;
 
     return {
       templatesRoot: path.resolve(process.cwd(), env.COMMUNICATIONS_TEMPLATES_ROOT),
       email: {
         provider: env.COMMUNICATIONS_EMAIL_PROVIDER,
-        from: env.COMMUNICATIONS_EMAIL_FROM,
+        from: derivedFrom,
         replyTo: env.COMMUNICATIONS_EMAIL_REPLY_TO || null,
         subjectPrefix: env.COMMUNICATIONS_EMAIL_SUBJECT_PREFIX || null,
         smtp: {

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

@@ -1,19 +1,35 @@
-import { z } from 'zod';
+import { z } from 'zod';
+
+function normalizeEnvBoolean(value: unknown): unknown {
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (['true', '1', 'yes', 'on'].includes(normalized)) {
+      return true;
+    }
+    if (['false', '0', 'no', 'off', ''].includes(normalized)) {
+      return false;
+    }
+  }
+
+  return value;
+}
+
+const envBoolean = z.preprocess(normalizeEnvBoolean, z.boolean());
 
 export const communicationsEnvSchema = z
   .object({
     COMMUNICATIONS_TEMPLATES_ROOT: z.string().trim().min(1).default('resources/communications'),
     COMMUNICATIONS_EMAIL_PROVIDER: z.enum(['gmail-smtp']).default('gmail-smtp'),
-    COMMUNICATIONS_EMAIL_FROM: z.string().trim().min(1).default('Forgeon <no-reply@example.com>'),
+    COMMUNICATIONS_EMAIL_FROM: z.string().trim().default(''),
     COMMUNICATIONS_EMAIL_REPLY_TO: z.string().trim().default(''),
     COMMUNICATIONS_EMAIL_SUBJECT_PREFIX: z.string().trim().default('[Forgeon]'),
     COMMUNICATIONS_EMAIL_SMTP_HOST: z.string().trim().min(1).default('smtp.gmail.com'),
     COMMUNICATIONS_EMAIL_SMTP_PORT: z.coerce.number().int().min(1).max(65535).default(587),
-    COMMUNICATIONS_EMAIL_SMTP_SECURE: z.coerce.boolean().default(false),
+    COMMUNICATIONS_EMAIL_SMTP_SECURE: envBoolean.default(false),
     COMMUNICATIONS_EMAIL_SMTP_USER: z.string().trim().default(''),
     COMMUNICATIONS_EMAIL_SMTP_PASS: z.string().trim().default(''),
     COMMUNICATIONS_SMS_PROVIDER: z.enum(['stub']).default('stub'),
-    COMMUNICATIONS_PUSH_PROVIDER: z.enum(['stub']).default('stub')
+    COMMUNICATIONS_PUSH_PROVIDER: z.enum(['stub']).default('stub'),
   })
   .passthrough();
 
@@ -21,4 +37,4 @@ export type CommunicationsEnv = z.infer<typeof communicationsEnvSchema>;
 
 export function parseCommunicationsEnv(input: Record<string, unknown>): CommunicationsEnv {
   return communicationsEnvSchema.parse(input);
-}
+}

package/templates/module-presets/communications/packages/communications/src/email/providers/gmail-smtp-email.provider.ts

@@ -6,6 +6,7 @@ import type { EmailProvider, EmailProviderSendInput, EmailProviderSendResult } f
 
 const EMAIL_ERROR_CODES = {
   providerNotConfigured: 'COMMUNICATIONS_EMAIL_PROVIDER_NOT_CONFIGURED',
+  providerSendFailed: 'COMMUNICATIONS_EMAIL_PROVIDER_SEND_FAILED',
 } as const;
 
 @Injectable()
@@ -30,20 +31,33 @@ export class GmailSmtpEmailProvider implements EmailProvider {
       });
     }
 
-    const response = await this.getTransporter().sendMail({
-      from: this.configService.emailFrom,
-      to: input.to,
-      subject: input.subject,
-      html: input.html,
-      replyTo: input.replyTo ?? this.configService.emailReplyTo ?? undefined,
-    });
+    try {
+      const response = await this.getTransporter().sendMail({
+        from: this.configService.emailFrom,
+        to: input.to,
+        subject: input.subject,
+        html: input.html,
+        replyTo: input.replyTo ?? this.configService.emailReplyTo ?? undefined,
+      });
 
-    this.logger.log(`email.sent provider=${this.providerId} to=${input.to} messageId=${response.messageId ?? 'n/a'}`);
+      this.logger.log(`email.sent provider=${this.providerId} to=${input.to} messageId=${response.messageId ?? 'n/a'}`);
 
-    return {
-      status: 'sent',
-      messageId: response.messageId ?? null,
-    };
+      return {
+        status: 'sent',
+        messageId: response.messageId ?? null,
+      };
+    } catch (error) {
+      const details = this.extractErrorDetails(error);
+      this.logger.error(`email.failed provider=${this.providerId} to=${input.to} details=${JSON.stringify(details)}`);
+      throw new ServiceUnavailableException({
+        message: 'Email delivery failed',
+        details: {
+          code: EMAIL_ERROR_CODES.providerSendFailed,
+          provider: this.providerId,
+          ...details,
+        },
+      });
+    }
   }
 
   private getTransporter(): Transporter {
@@ -61,4 +75,30 @@ export class GmailSmtpEmailProvider implements EmailProvider {
 
     return this.transporter;
   }
+
+  private extractErrorDetails(error: unknown): Record<string, unknown> {
+    if (!error || typeof error !== 'object') {
+      return { raw: String(error) };
+    }
+
+    const candidate = error as {
+      code?: unknown;
+      command?: unknown;
+      response?: unknown;
+      responseCode?: unknown;
+      errno?: unknown;
+      syscall?: unknown;
+      message?: unknown;
+    };
+
+    return {
+      message: typeof candidate.message === 'string' ? candidate.message : String(error),
+      code: candidate.code ?? null,
+      command: candidate.command ?? null,
+      responseCode: candidate.responseCode ?? null,
+      response: candidate.response ?? null,
+      errno: candidate.errno ?? null,
+      syscall: candidate.syscall ?? null,
+    };
+  }
 }

package/templates/module-presets/communications/packages/communications/src/forgeon-communications.module.ts

@@ -1,4 +1,4 @@
-import { DynamicModule, Module, ModuleMetadata } from '@nestjs/common';
+import { DynamicModule, Global, Module, ModuleMetadata } from '@nestjs/common';
 import {
   COMMUNICATIONS_EMAIL_PROVIDER,
   COMMUNICATIONS_PUSH_PROVIDER,
@@ -20,6 +20,7 @@ export interface ForgeonCommunicationsModuleOptions {
   imports?: ModuleMetadata['imports'];
 }
 
+@Global()
 @Module({})
 export class ForgeonCommunicationsModule {
   static register(options: ForgeonCommunicationsModuleOptions = {}): DynamicModule {