@aurorajs.dev/catalyst-cli 1.0.0

package/dist/templates/backend/application/src/@aurora/modules/graphql/guards/gql-throttler.guard.ts

@@ -0,0 +1,22 @@
+import { Api } from '@aurorajs.dev/core-back';
+import { ExecutionContext, Injectable } from '@nestjs/common';
+import { ThrottlerGuard } from '@nestjs/throttler';
+
+/**
+ * `ThrottlerGuard` variant for GraphQL resolvers. The stock guard reads the request/response
+ * via `context.switchToHttp()`, which is empty under a GraphQL execution context. This override
+ * resolves them with the project's canonical `Api.getRequestFromExecutionContext` (the same
+ * helper `AuthenticationJwtGuard` uses) — the Apollo context exposes `req` via
+ * `context: ({ req }) => ({ req })` in `graphql-config.module.ts`, and Express attaches the
+ * response as `req.res` (used by the throttler to set the `Retry-After` header).
+ */
+@Injectable()
+export class GqlThrottlerGuard extends ThrottlerGuard {
+  protected getRequestResponse(context: ExecutionContext): {
+    req: Record<string, any>;
+    res: Record<string, any>;
+  } {
+    const req = Api.getRequestFromExecutionContext<Record<string, any>>(context);
+    return { req, res: req.res };
+  }
+}

package/dist/templates/backend/application/src/@aurora/modules/graphql/hello.resolver.ts

@@ -0,0 +1,9 @@
+import { Query, Resolver } from '@nestjs/graphql';
+
+@Resolver()
+export class Hello {
+  @Query('hello')
+  main(): string {
+    return 'Hello world!';
+  }
+}

package/dist/templates/backend/application/src/@aurora/modules/graphql/index.ts

@@ -0,0 +1,3 @@
+export { GraphQLConfigModule } from './graphql-config.module';
+export { GqlThrottlerGuard } from './guards/gql-throttler.guard';
+export { SchemaStoreService } from './schema-store.service';

package/dist/templates/backend/application/src/@aurora/modules/graphql/schema-store.module.ts

@@ -0,0 +1,9 @@
+import { Global, Module } from '@nestjs/common';
+import { SchemaStoreService } from './schema-store.service';
+
+@Global()
+@Module({
+  providers: [SchemaStoreService],
+  exports: [SchemaStoreService],
+})
+export class SchemaStoreModule {}

package/dist/templates/backend/application/src/@aurora/modules/graphql/schema-store.service.ts

@@ -0,0 +1,23 @@
+import { Injectable } from '@nestjs/common';
+import { GraphQLSchema, printSchema } from 'graphql';
+
+@Injectable()
+export class SchemaStoreService {
+  private schema?: GraphQLSchema;
+  private sdl?: string;
+
+  load(schema: GraphQLSchema): void {
+    this.schema = schema;
+    this.sdl = printSchema(schema);
+  }
+
+  getSchema(): GraphQLSchema {
+    if (!this.schema) throw new Error('The GraphQL schema is not yet available');
+    return this.schema;
+  }
+
+  getSDL(): string {
+    if (!this.sdl) throw new Error('The GraphQL SDL is not yet available');
+    return this.sdl;
+  }
+}

package/dist/templates/backend/application/src/@aurora/modules/index.ts

@@ -0,0 +1,5 @@
+export * from './criteria';
+export * from './graphql';
+export * from './lang';
+export * from './mailer';
+export * from './server-static';

package/dist/templates/backend/application/src/@aurora/modules/lang/core-get-fallback-lang-from-json.service.ts

@@ -0,0 +1,38 @@
+import { CoreLang } from '@api/graphql';
+import { CoreGetFallbackLangService } from '@aurorajs.dev/core-back';
+import { CACHE_MANAGER } from '@nestjs/cache-manager';
+import { Inject, Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { Cache } from 'cache-manager';
+import { coreLangs } from './core-langs';
+
+@Injectable()
+export class CoreGetFallbackLangFromJsonService implements CoreGetFallbackLangService {
+  constructor(
+    @Inject(CACHE_MANAGER) private readonly cacheManager: Cache,
+    private readonly configService: ConfigService,
+  ) {}
+
+  async get<T>(): Promise<T> {
+    // return cache langs
+    const lang = await this.cacheManager.get<T>('common/fallback-lang');
+    if (coreLangs) return lang;
+
+    // get langs from json and return cache langs if cache is expired
+    await this.init();
+    return await this.cacheManager.get<T>('common/fallback-lang');
+  }
+
+  async init(): Promise<void> {
+    await this.cacheManager.set('common/fallback-lang', this.getJsonFallbackLang());
+  }
+
+  getJsonFallbackLang(): CoreLang {
+    const fallbackLangIso6392 = this.configService.get('APP_FALLBACK_LANG');
+    return coreLangs.find((lang) => lang.iso6392 === fallbackLangIso6392);
+  }
+
+  onApplicationBootstrap(): void {
+    this.init();
+  }
+}

package/dist/templates/backend/application/src/@aurora/modules/lang/core-get-langs-from-json.service.ts

@@ -0,0 +1,33 @@
+import { CoreLang } from '@api/graphql';
+import { CoreGetLangsService } from '@aurorajs.dev/core-back';
+import { CACHE_MANAGER } from '@nestjs/cache-manager';
+import { Inject, Injectable } from '@nestjs/common';
+import { Cache } from 'cache-manager';
+import { coreLangs } from './core-langs';
+
+@Injectable()
+export class CoreGetLangsFromJsonService implements CoreGetLangsService {
+  constructor(@Inject(CACHE_MANAGER) private readonly cacheManager: Cache) {}
+
+  async get<T>(): Promise<T[]> {
+    // return cache langs
+    const langs = await this.cacheManager.get<T[]>('common/langs');
+    if (langs) return langs;
+
+    // get langs from json and return cache langs if cache is expired
+    await this.init();
+    return await this.cacheManager.get<T[]>('common/langs');
+  }
+
+  async init(): Promise<void> {
+    await this.cacheManager.set('common/langs', this.getJsonLangs());
+  }
+
+  getJsonLangs(): CoreLang[] {
+    return coreLangs;
+  }
+
+  onApplicationBootstrap(): void {
+    void this.init();
+  }
+}

package/dist/templates/backend/application/src/@aurora/modules/lang/core-langs.ts

@@ -0,0 +1,64 @@
+import { CoreLang, CoreLangDir } from '@api/graphql';
+
+export const coreLangs: CoreLang[] = [
+  {
+    id: '94c893c1-3eb7-4f22-a878-b405c6d42e09',
+    name: 'Deutsch',
+    image: 'de',
+    iso6392: 'de',
+    iso6393: 'deu',
+    ietf: 'de-DE',
+    customCode: null,
+    dir: CoreLangDir.RTL,
+    sort: 0,
+    isActive: false,
+  },
+  {
+    id: '7c4754e7-3363-48ca-af99-632522226b51',
+    name: 'English',
+    image: 'us',
+    iso6392: 'en',
+    iso6393: 'eng',
+    ietf: 'en-US',
+    customCode: null,
+    dir: CoreLangDir.RTL,
+    sort: 0,
+    isActive: true,
+  },
+  {
+    id: '4470b5ab-9d57-4c9d-a68f-5bf8e32f543a',
+    name: 'Español',
+    image: 'es',
+    iso6392: 'es',
+    iso6393: 'spa',
+    ietf: 'es-ES',
+    customCode: null,
+    dir: CoreLangDir.RTL,
+    sort: 1,
+    isActive: true,
+  },
+  {
+    id: '47ecef11-3d7d-426b-967d-31f2f737b65c',
+    name: 'Français',
+    image: 'fr',
+    iso6392: 'fr',
+    iso6393: 'fra',
+    ietf: 'fr-FR',
+    customCode: null,
+    dir: CoreLangDir.RTL,
+    sort: 0,
+    isActive: false,
+  },
+  {
+    id: 'dbf8a12d-70af-4a83-adb7-209daf56ab64',
+    name: 'Português',
+    image: 'pt',
+    iso6392: 'pt',
+    iso6393: 'por',
+    ietf: 'pt-PT',
+    customCode: null,
+    dir: CoreLangDir.RTL,
+    sort: 0,
+    isActive: false,
+  },
+];

package/dist/templates/backend/application/src/@aurora/modules/lang/index.ts

@@ -0,0 +1,3 @@
+export { CoreGetFallbackLangFromJsonService } from './core-get-fallback-lang-from-json.service';
+export { CoreGetLangsFromJsonService } from './core-get-langs-from-json.service';
+export { coreLangs } from './core-langs';

package/dist/templates/backend/application/src/@aurora/modules/mailer/index.ts

@@ -0,0 +1 @@
+export { MailerCLientModule } from './mailer-client.module';

package/dist/templates/backend/application/src/@aurora/modules/mailer/mailer-client.module.spec.ts

@@ -0,0 +1,178 @@
+/**
+ * Unit test for MailerCLientModule wiring.
+ *
+ * Tests what is realistically unit-testable (per design D5):
+ * (a) Disabled path: forRootAsync() returns a bare module with no imports when MAILER_ENABLED !== 'true'.
+ * (b) Enabled path: forRootAsync() includes imports (MailerModule + I18nModule).
+ * (c) Adapter type: the useFactory builds a config whose template.adapter is a MjmlAdapter instance.
+ * (d) t helper: the t helper is a callable function that delegates to I18nService.t.
+ *
+ * Strategy: mock @nestjs-modules/mailer and nestjs-i18n so their module bootstrapping
+ * does NOT run. We intercept the useFactory from the MailerModule.forRootAsync call
+ * to test the adapter config in isolation.
+ */
+
+import { MjmlAdapter } from '@nestjs-modules/mailer/adapters/mjml.adapter';
+import { DynamicModule } from '@nestjs/common';
+
+// Capture the factory that the module registers via MailerModule.forRootAsync.
+// We set this variable inside the mock so the test can call the factory directly.
+let capturedFactory: ((...args: unknown[]) => unknown) | undefined;
+
+jest.mock('@nestjs-modules/mailer', () => {
+  return {
+    MailerModule: {
+      forRootAsync: jest.fn((opts: { useFactory?: (...args: unknown[]) => unknown }) => {
+        if (opts?.useFactory) {
+          capturedFactory = opts.useFactory;
+        }
+        return { module: class MockMailerModule {}, providers: [] };
+      }),
+    },
+  };
+});
+
+jest.mock('nestjs-i18n', () => {
+  const AcceptLanguageResolver = class {};
+  const QueryResolver = class {};
+  const I18nModule = {
+    forRoot: jest.fn(() => ({ module: class MockI18nModule {} })),
+  };
+  return { AcceptLanguageResolver, QueryResolver, I18nModule, I18nService: class {} };
+});
+
+jest.mock('@config/mailer', () => ({
+  MailerTransportModule: class MockMailerTransportModule {},
+}));
+
+// Import the module under test AFTER the mocks are registered by jest.mock() (which is hoisted).
+
+const { MailerCLientModule } = require('./mailer-client.module') as {
+  MailerCLientModule: { forRootAsync: () => DynamicModule };
+};
+
+describe('MailerCLientModule.forRootAsync()', () => {
+  const ORIGINAL_MAILER_ENABLED = process.env.MAILER_ENABLED;
+
+  beforeEach(() => {
+    capturedFactory = undefined;
+    jest.clearAllMocks();
+  });
+
+  afterAll(() => {
+    if (ORIGINAL_MAILER_ENABLED === undefined) {
+      delete process.env.MAILER_ENABLED;
+    } else {
+      process.env.MAILER_ENABLED = ORIGINAL_MAILER_ENABLED;
+    }
+  });
+
+  // ─── Disabled path ──────────────────────────────────────────────────────────
+
+  describe('disabled path (MAILER_ENABLED !== "true")', () => {
+    it('returns a bare dynamic module with no imports when MAILER_ENABLED is unset', () => {
+      delete process.env.MAILER_ENABLED;
+
+      const mod = MailerCLientModule.forRootAsync();
+
+      expect(mod.module).toBe(MailerCLientModule);
+      expect(mod.imports).toBeUndefined();
+    });
+
+    it('returns a bare dynamic module with no imports when MAILER_ENABLED is "false"', () => {
+      process.env.MAILER_ENABLED = 'false';
+
+      const mod = MailerCLientModule.forRootAsync();
+
+      expect(mod.module).toBe(MailerCLientModule);
+      expect(mod.imports).toBeUndefined();
+    });
+  });
+
+  // ─── Enabled path ───────────────────────────────────────────────────────────
+
+  describe('enabled path (MAILER_ENABLED === "true")', () => {
+    beforeEach(() => {
+      process.env.MAILER_ENABLED = 'true';
+    });
+
+    afterEach(() => {
+      delete process.env.MAILER_ENABLED;
+    });
+
+    it('returns a dynamic module with imports when the mailer is enabled', () => {
+      const mod = MailerCLientModule.forRootAsync();
+
+      expect(mod.module).toBe(MailerCLientModule);
+      expect(Array.isArray(mod.imports)).toBe(true);
+      expect((mod.imports as unknown[]).length).toBeGreaterThan(0);
+    });
+
+    it('configures the template adapter as an instance of MjmlAdapter, not HandlebarsAdapter', () => {
+      MailerCLientModule.forRootAsync(); // triggers capturedFactory capture via the mock
+
+      expect(capturedFactory).toBeDefined();
+
+      const mockConfigService = { get: jest.fn().mockReturnValue('noreply@example.com') };
+      const mockI18nService = { t: jest.fn((key: string) => key) };
+      const mockMailerTransportService = {
+        getTransport: jest.fn().mockReturnValue({ host: 'smtp.example.com' }),
+      };
+
+      const config = capturedFactory(
+        mockConfigService,
+        mockI18nService,
+        mockMailerTransportService,
+      ) as { template: { adapter: unknown } };
+
+      const adapter = config?.template?.adapter;
+
+      // (b) The adapter MUST be an instance of MjmlAdapter, NOT a bare HandlebarsAdapter.
+      expect(adapter).toBeInstanceOf(MjmlAdapter);
+    });
+
+    it('invokes the wired t helper (backed by I18nService) when a template renders {{t}}', (done) => {
+      MailerCLientModule.forRootAsync();
+
+      expect(capturedFactory).toBeDefined();
+
+      const i18nSpy = jest.fn((_key: string, _opts?: unknown) => 'TRANSLATED');
+      const config = capturedFactory(
+        { get: jest.fn().mockReturnValue('noreply@example.com') },
+        { t: i18nSpy },
+        { getTransport: jest.fn().mockReturnValue({ host: 'smtp.example.com' }) },
+      ) as { template: { adapter: InstanceType<typeof MjmlAdapter>; dir: string } };
+
+      const mail: { data: { template: string; context: Record<string, unknown>; html?: string } } =
+        {
+          data: {
+            template: 'forgot-password.mjml',
+            context: {
+              username: 'alice',
+              email: 'alice@example.com',
+              resetLink: 'https://x.example.com/reset',
+              validHours: 24,
+            },
+          },
+        };
+
+      config.template.adapter.compile(
+        mail,
+        (err?: unknown) => {
+          try {
+            expect(err).toBeFalsy();
+            // The wired i18nSpy (the REAL I18nService mock) must have been invoked by the template.
+            expect(i18nSpy).toHaveBeenCalledWith(
+              'iam.PasswordRecovery',
+              expect.objectContaining({ lang: 'en' }),
+            );
+            done();
+          } catch (e) {
+            done(e as Error);
+          }
+        },
+        { template: { dir: config.template.dir } },
+      );
+    });
+  });
+});

package/dist/templates/backend/application/src/@aurora/modules/mailer/mailer-client.module.ts

@@ -0,0 +1,74 @@
+import { MailerTransportService } from '@aurorajs.dev/core-back';
+import { MailerTransportModule } from '@config/mailer';
+import { MailerModule } from '@nestjs-modules/mailer';
+import { MjmlAdapter } from '@nestjs-modules/mailer/adapters/mjml.adapter';
+import { DynamicModule, Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { AcceptLanguageResolver, I18nModule, I18nService, QueryResolver } from 'nestjs-i18n';
+import { join } from 'node:path';
+
+const customI18nHelper = (i18nService: I18nService) => {
+  return (key: string, context: any) => {
+    const lang = context?.data?.root?.lang || 'en';
+    const args = context?.hash || {};
+    return i18nService.t(key, { lang, args });
+  };
+};
+
+@Module({})
+export class MailerCLientModule {
+  public static forRootAsync(): DynamicModule {
+    if (process.env.MAILER_ENABLED !== 'true') {
+      return {
+        module: MailerCLientModule,
+      };
+    }
+
+    const srcPath = join(__dirname, '..', '..', '..');
+
+    return {
+      module: MailerCLientModule,
+      imports: [
+        I18nModule.forRoot({
+          fallbackLanguage: 'en',
+          loaderOptions: {
+            path: join(srcPath, 'i18n'),
+            watch: true,
+          },
+          resolvers: [
+            {
+              use: QueryResolver,
+              options: ['lang'],
+            },
+            AcceptLanguageResolver,
+          ],
+        }),
+        MailerModule.forRootAsync({
+          imports: [ConfigModule, MailerTransportModule],
+          inject: [ConfigService, I18nService, MailerTransportService],
+          useFactory: (
+            configService: ConfigService,
+            i18nService: I18nService,
+            mailerTransportService: MailerTransportService,
+          ) => ({
+            transport: mailerTransportService.getTransport(),
+            defaults: {
+              from: configService.get<string>('MAILER_FROM'),
+            },
+            template: {
+              dir: join(srcPath, 'assets', 'email', 'templates'),
+              adapter: new MjmlAdapter(
+                'handlebars',
+                { inlineCssEnabled: false },
+                { handlebar: { helper: { t: customI18nHelper(i18nService) } } },
+              ),
+              options: {
+                strict: true,
+              },
+            },
+          }),
+        }),
+      ],
+    };
+  }
+}

package/dist/templates/backend/application/src/@aurora/modules/mailer/mailer-smtp-transport.service.ts

@@ -0,0 +1,24 @@
+import { MailerTransportService } from '@aurorajs.dev/core-back';
+import { MailerOptions } from '@nestjs-modules/mailer';
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+
+@Injectable()
+export class MailerSMTPTransportService extends MailerTransportService {
+  constructor(private readonly configService: ConfigService) {
+    super();
+  }
+
+  getTransport(): MailerOptions['transport'] {
+    return {
+      host: this.configService.get<string>('MAILER_HOST'),
+      port: +this.configService.get<number>('MAILER_PORT'),
+      ignoreTLS: this.configService.get<string>('MAILER_IGNORE_TLS') === 'true' ? true : false,
+      secure: this.configService.get<string>('MAILER_SECURE') === 'true' ? true : false,
+      auth: {
+        user: this.configService.get<string>('MAILER_USER'),
+        pass: this.configService.get<string>('MAILER_PASSWORD'),
+      },
+    };
+  }
+}

package/dist/templates/backend/application/src/@aurora/modules/server-static/index.ts

@@ -0,0 +1 @@
+export { ServerStaticModule } from './server-static.module';

package/dist/templates/backend/application/src/@aurora/modules/server-static/server-static.module.ts

@@ -0,0 +1,20 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { ServeStaticModule } from '@nestjs/serve-static';
+import { join } from 'path';
+
+@Module({
+  imports: [
+    ServeStaticModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (configService: ConfigService) => [
+        {
+          rootPath: join(process.cwd(), configService.get('STORAGE_ACCOUNT_PUBLIC_PATH')),
+          serveRoot: `/${configService.get('STORAGE_ACCOUNT_PUBLIC_PATH')}`,
+        },
+      ],
+    }),
+  ],
+})
+export class ServerStaticModule {}

package/dist/templates/backend/application/src/@aurora/services/bootstrap-gate.ts

@@ -0,0 +1,20 @@
+/**
+ * Gate function for bootstrap seeders.
+ *
+ * Returns true when either:
+ *   - BOOTSTRAP_SEED=true is set explicitly, OR
+ *   - NODE_ENV is not 'production' (development, test, undefined).
+ *
+ * This is the single source of truth for the gate — both IamBootstrapSeeder
+ * and OAuthBootstrapSeeder import from here. The gate is a pure process.env
+ * function with zero BC coupling, so it belongs in @aurora/ (framework/config).
+ *
+ * @aurora imports nothing from @app / BC-scoped @api — that direction is forbidden.
+ * @app and @api importing from @aurora is the allowed direction.
+ */
+
+/** Returns true when the bootstrap seeders should run. */
+export const bootstrapSeederIsEnabled = (): boolean => {
+  if (process.env.BOOTSTRAP_SEED === 'true') return true;
+  return process.env.NODE_ENV !== 'production';
+};

package/dist/templates/backend/application/src/@aurora/services/bootstrap.service.ts

@@ -0,0 +1,20 @@
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { Sequelize } from 'sequelize-typescript';
+
+@Injectable()
+export class BootstrapService {
+  constructor(
+    private readonly configService: ConfigService,
+    private readonly sequelize: Sequelize,
+  ) {}
+
+  async onApplicationBootstrap(): Promise<void> {
+    if (
+      this.configService.get('DATABASE_SYNCHRONIZE') === 'true' &&
+      this.configService.get('DATABASE_SYNCHRONIZE_ALTER') === 'true'
+    ) {
+      await this.sequelize.sync({ alter: true });
+    }
+  }
+}

package/dist/templates/backend/application/src/@aurora/services/index.ts

@@ -0,0 +1,3 @@
+export * from './bootstrap-gate';
+export * from './bootstrap.service';
+export * from './logger.service';

package/dist/templates/backend/application/src/@aurora/services/logger.service.ts

@@ -0,0 +1,60 @@
+import { LoggerService } from '@nestjs/common';
+import chalk from 'chalk';
+import { WinstonModule } from 'nest-winston';
+import winston from 'winston';
+
+export const logger = (): LoggerService => {
+  return WinstonModule.createLogger({
+    level: 'info',
+    format: winston.format.combine(winston.format.splat(), winston.format.simple()),
+    transports: [
+      new winston.transports.File({
+        filename: process.env.LOGGER_ERROR_LOG_PATH,
+        level: 'error',
+        maxsize: 5242880,
+        maxFiles: 5,
+        format: winston.format.combine(
+          winston.format.timestamp({
+            format: 'DD/MM/YYYY HH:mm:ss',
+          }),
+          winston.format.label({ label: 'LOG' }),
+          winston.format.simple(),
+          winston.format.printf(({ level, message, label, timestamp, context }) => {
+            return `${timestamp}   ${label} [${context}] ${message}`;
+          }),
+        ),
+      }),
+      new winston.transports.File({
+        filename: process.env.LOGGER_CONSOLE_LOG_PATH,
+        maxsize: 5242880,
+        maxFiles: 5,
+        format: winston.format.combine(
+          winston.format.timestamp({
+            format: 'DD/MM/YYYY HH:mm:ss',
+          }),
+          winston.format.label({ label: 'LOG' }),
+          winston.format.simple(),
+          winston.format.printf(({ level, message, label, timestamp, context }) => {
+            return `${timestamp}   ${label} [${context}] ${message}`;
+          }),
+        ),
+      }),
+      new winston.transports.Console({
+        level: 'info',
+        format: winston.format.combine(
+          winston.format.colorize({
+            all: true,
+          }),
+          winston.format.timestamp({
+            format: 'DD/MM/YYYY HH:mm:ss',
+          }),
+          winston.format.label({ label: 'LOG' }),
+          winston.format.simple(),
+          winston.format.printf(({ level, message, label, timestamp, context }) => {
+            return chalk`${timestamp}   {keyword('green') ${label}} {keyword('yellow') [${context}]} ${message}`;
+          }),
+        ),
+      }),
+    ],
+  });
+};