@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/strategies/local-provider/local-provider.adapter.ts

@@ -10,9 +10,9 @@ import {
   type AuthenticatedAccount,
   type IAccountLoader,
   type IAuthenticationStrategy,
-} from '../../../domain/ports';
-import { resolveAuthenticationMode } from '../../../domain/resolve-authentication-mode';
-import { buildJwtAccountCacheKey } from '../cache-key';
+} from '../../../domain/ports/index.js';
+import { resolveAuthenticationMode } from '../../../domain/resolve-authentication-mode.js';
+import { buildJwtAccountCacheKey } from '../cache-key.js';
 
 const ISSUER = 'Aurora Catalyst';
 const DEFAULT_PUBLIC_KEY_PATH = './.keys/oauth-public.key';

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/warnings/authentication-boot-warning.spec.ts

@@ -2,23 +2,24 @@
  * Unit test for the authentication boot warning.
  * Verifies that a prominent warning is logged when OAUTH_STRATEGY=none.
  */
+import type { Mock } from 'vitest';
 import { Logger } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { Test } from '@nestjs/testing';
-import { AuthenticationBootWarning } from './authentication-boot-warning';
+import { AuthenticationBootWarning } from './authentication-boot-warning.js';
 
 describe('AuthenticationBootWarning', () => {
   let service: AuthenticationBootWarning;
-  let configService: { get: jest.Mock };
+  let configService: { get: Mock };
 
   afterEach(() => {
-    jest.restoreAllMocks();
+    vi.restoreAllMocks();
   });
 
   describe('when OAUTH_STRATEGY=none', () => {
     beforeEach(async () => {
       configService = {
-        get: jest.fn((key: string) => {
+        get: vi.fn((key: string) => {
           if (key === 'OAUTH_STRATEGY') return 'none';
           return undefined;
         }),
@@ -32,7 +33,7 @@ describe('AuthenticationBootWarning', () => {
     });
 
     it('emits a prominent warn log naming OAUTH_STRATEGY=none on onModuleInit', () => {
-      const warnSpy = jest.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
+      const warnSpy = vi.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
 
       service.onModuleInit();
 
@@ -42,7 +43,7 @@ describe('AuthenticationBootWarning', () => {
     });
 
     it('emits a log that mentions anonymous access', () => {
-      const warnSpy = jest.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
+      const warnSpy = vi.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
 
       service.onModuleInit();
 
@@ -54,7 +55,7 @@ describe('AuthenticationBootWarning', () => {
   describe('when OAUTH_STRATEGY=aurora-hub', () => {
     beforeEach(async () => {
       configService = {
-        get: jest.fn((key: string) => {
+        get: vi.fn((key: string) => {
           if (key === 'OAUTH_STRATEGY') return 'aurora-hub';
           return undefined;
         }),
@@ -68,7 +69,7 @@ describe('AuthenticationBootWarning', () => {
     });
 
     it('does NOT emit a warn log when mode is aurora-hub', () => {
-      const warnSpy = jest.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
+      const warnSpy = vi.spyOn(Logger.prototype, 'warn').mockImplementation(() => undefined);
 
       service.onModuleInit();
 

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/warnings/authentication-boot-warning.ts

@@ -1,6 +1,6 @@
 import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
-import { resolveAuthenticationMode } from '../../domain/resolve-authentication-mode';
+import { resolveAuthenticationMode } from '../../domain/resolve-authentication-mode.js';
 
 /**
  * Emits a prominent boot-time warning when `OAUTH_STRATEGY=none`.

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

@@ -1 +1 @@
-export { CriteriaConfigModule } from './criteria-config.module';
+export { CriteriaConfigModule } from './criteria-config.module.js';

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

@@ -6,9 +6,9 @@ import { GraphQLModule } from '@nestjs/graphql';
 import { GraphQLSchema } from 'graphql';
 import GraphQLJSON from 'graphql-type-json';
 import { join } from 'path';
-import { Hello } from './hello.resolver';
-import { SchemaStoreModule } from './schema-store.module';
-import { SchemaStoreService } from './schema-store.service';
+import { Hello } from './hello.resolver.js';
+import { SchemaStoreModule } from './schema-store.module.js';
+import { SchemaStoreService } from './schema-store.service.js';
 
 @Module({
   imports: [

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

@@ -1,16 +1,17 @@
+import type { Mock } from 'vitest';
 import { ExecutionContext } from '@nestjs/common';
 
-jest.mock('@aurorajs.dev/core-back', () => ({
-  Api: { getRequestFromExecutionContext: jest.fn() },
+vi.mock('@aurorajs.dev/core-back', () => ({
+  Api: { getRequestFromExecutionContext: vi.fn() },
 }));
 
 import { Api } from '@aurorajs.dev/core-back';
-import { GqlThrottlerGuard } from './gql-throttler.guard';
+import { GqlThrottlerGuard } from './gql-throttler.guard.js';
 
 type RequestResponse = { req: Record<string, unknown>; res: Record<string, unknown> };
 
 describe('GqlThrottlerGuard', () => {
-  afterEach(() => jest.clearAllMocks());
+  afterEach(() => vi.clearAllMocks());
 
   // getRequestResponse is protected; instantiate without the ThrottlerGuard constructor deps
   // (the override does not touch them) and access the method through a narrowed cast.
@@ -22,9 +23,9 @@ describe('GqlThrottlerGuard', () => {
   };
 
   it('resolves { req, res } from the dual-context request via Api.getRequestFromExecutionContext', () => {
-    const res = { setHeader: jest.fn() };
+    const res = { setHeader: vi.fn() };
     const req = { ip: '203.0.113.7', res };
-    (Api.getRequestFromExecutionContext as jest.Mock).mockReturnValue(req);
+    (Api.getRequestFromExecutionContext as Mock).mockReturnValue(req);
 
     const result = callGetRequestResponse({} as ExecutionContext);
 

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

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

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

@@ -1,5 +1,5 @@
 import { Global, Module } from '@nestjs/common';
-import { SchemaStoreService } from './schema-store.service';
+import { SchemaStoreService } from './schema-store.service.js';
 
 @Global()
 @Module({

package/dist/templates/backend/application/src/@aurora/modules/handler-registry/event-dispatcher.spec.ts

@@ -1,9 +1,9 @@
 import { Injectable, Provider } from '@nestjs/common';
 import { DiscoveryModule } from '@nestjs/core';
 import { Test, TestingModule } from '@nestjs/testing';
-import { Dispatchable, EventDispatcher } from './event-dispatcher';
-import { Handler } from './handler.decorator';
-import { KeyedHandlerRegistry } from './keyed-handler-registry';
+import { Dispatchable, EventDispatcher } from './event-dispatcher.js';
+import { Handler } from './handler.decorator.js';
+import { KeyedHandlerRegistry } from './keyed-handler-registry.js';
 
 // ---------------------------------------------------------------------------
 // Fake Dispatchable handlers — used across scenarios

package/dist/templates/backend/application/src/@aurora/modules/handler-registry/event-dispatcher.ts

@@ -1,5 +1,5 @@
 import { Injectable } from '@nestjs/common';
-import { KeyedHandlerRegistry } from './keyed-handler-registry';
+import { KeyedHandlerRegistry } from './keyed-handler-registry.js';
 
 /**
  * Contract for any handler that participates in single-method fan-out dispatch.

package/dist/templates/backend/application/src/@aurora/modules/handler-registry/handler-registry.module.ts

@@ -1,7 +1,7 @@
 import { Global, Module } from '@nestjs/common';
 import { DiscoveryModule } from '@nestjs/core';
-import { EventDispatcher } from './event-dispatcher';
-import { KeyedHandlerRegistry } from './keyed-handler-registry';
+import { EventDispatcher } from './event-dispatcher.js';
+import { KeyedHandlerRegistry } from './keyed-handler-registry.js';
 
 /**
  * Framework-level module that makes `KeyedHandlerRegistry` and `EventDispatcher`

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

@@ -1,4 +1,4 @@
-export { Dispatchable, EventDispatcher } from './event-dispatcher';
-export { HandlerRegistryModule } from './handler-registry.module';
-export { HANDLER_KEYS, Handler } from './handler.decorator';
-export { KeyedHandlerRegistry } from './keyed-handler-registry';
+export { Dispatchable, EventDispatcher } from './event-dispatcher.js';
+export { HandlerRegistryModule } from './handler-registry.module.js';
+export { HANDLER_KEYS, Handler } from './handler.decorator.js';
+export { KeyedHandlerRegistry } from './keyed-handler-registry.js';

package/dist/templates/backend/application/src/@aurora/modules/handler-registry/keyed-handler-registry.spec.ts

@@ -1,8 +1,8 @@
 import { Injectable } from '@nestjs/common';
 import { DiscoveryModule } from '@nestjs/core';
 import { Test, TestingModule } from '@nestjs/testing';
-import { Handler } from './handler.decorator';
-import { KeyedHandlerRegistry } from './keyed-handler-registry';
+import { Handler } from './handler.decorator.js';
+import { KeyedHandlerRegistry } from './keyed-handler-registry.js';
 
 // ---------------------------------------------------------------------------
 // Fake handler classes — used across scenarios

package/dist/templates/backend/application/src/@aurora/modules/handler-registry/keyed-handler-registry.ts

@@ -1,6 +1,6 @@
 import { Injectable, OnModuleInit } from '@nestjs/common';
 import { DiscoveryService } from '@nestjs/core';
-import { HANDLER_KEYS } from './handler.decorator';
+import { HANDLER_KEYS } from './handler.decorator.js';
 
 /**
  * Generic handler registry that discovers `@Handler`-decorated providers

package/dist/templates/backend/application/src/@aurora/modules/health/app-version.provider.spec.ts

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { readAppVersion } from './app-version.provider';
+import { readAppVersion } from './app-version.provider.js';
 
 describe('readAppVersion', () => {
   const fakePackageJsonPath = path.join('/private/tmp', 'fake-package.json');

package/dist/templates/backend/application/src/@aurora/modules/health/app-version.provider.ts

@@ -45,8 +45,9 @@ export function readAppVersion(packageJsonPath: string): string {
  * Resolves the backend `package.json` path at runtime (not at build time).
  * Primary: `process.cwd()/package.json` — works correctly when the NestJS process
  *           is started from the `backend/` directory (the normal case).
- * Fallback: walks up from __dirname until a `package.json` with `name === 'aurora-back'`
- *           is found, capped at 6 levels to avoid an infinite loop.
+ * Fallback: walks up from import.meta.dirname until a `package.json` with
+ *           `name === 'aurora-back'` is found, capped at 6 levels to avoid an
+ *           infinite loop.
  */
 export function resolvePackageJsonPath(): string {
   const cwdCandidate = path.join(process.cwd(), 'package.json');
@@ -68,7 +69,7 @@ export function resolvePackageJsonPath(): string {
   }
 
   // Walk up from this file's directory
-  let dir = __dirname;
+  let dir = import.meta.dirname;
   for (let depth = 0; depth < 6; depth++) {
     const candidate = path.join(dir, 'package.json');
     try {

package/dist/templates/backend/application/src/@aurora/modules/health/health.controller.spec.ts

@@ -1,5 +1,5 @@
 import { ThrottlerGuard } from '@nestjs/throttler';
-import { HealthController } from './health.controller';
+import { HealthController } from './health.controller.js';
 
 // @nestjs/throttler v6 stores metadata under string constants (not exported from the package
 // index). We read from the constants file directly to avoid coupling to implementation details.

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

@@ -1,6 +1,6 @@
 import { Controller, Get, Inject, UseGuards } from '@nestjs/common';
 import { Throttle, ThrottlerGuard } from '@nestjs/throttler';
-import { APP_VERSION } from './app-version.provider';
+import { APP_VERSION } from './app-version.provider.js';
 
 export interface HealthStatus {
   status: 'ok';

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

@@ -1,7 +1,7 @@
 import { Module } from '@nestjs/common';
 import { ThrottlerModule } from '@nestjs/throttler';
-import { appVersionProvider } from './app-version.provider';
-import { HealthController } from './health.controller';
+import { appVersionProvider } from './app-version.provider.js';
+import { HealthController } from './health.controller.js';
 
 /**
  * Self-contained health module. Exposes `GET /api/health` (global `api` prefix applied by main.ts).

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

@@ -1,3 +1,3 @@
-export * from './app-version.provider';
-export * from './health.controller';
-export * from './health.module';
+export * from './app-version.provider.js';
+export * from './health.controller.js';
+export * from './health.module.js';

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

@@ -1,9 +1,10 @@
-export * from './authentication';
-export * from './criteria';
-export * from './graphql';
-export * from './handler-registry';
-export * from './health';
-export * from './lang';
-export * from './mailer';
-export * from './report-engine';
-export * from './server-static';
+export * from './authentication/index.js';
+export * from './criteria/index.js';
+export * from './graphql/index.js';
+export * from './handler-registry/index.js';
+export * from './health/index.js';
+export * from './lang/index.js';
+export * from './mailer/index.js';
+export * from './pdf/index.js';
+export * from './report-engine/index.js';
+export * from './server-static/index.js';

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

@@ -1,10 +1,10 @@
-import { CoreLang } from '@api/graphql';
+import { CoreLang } from '@api/graphql.js';
 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';
+import { coreLangs } from './core-langs.js';
 
 @Injectable()
 export class CoreGetFallbackLangFromJsonService implements CoreGetFallbackLangService {
@@ -33,6 +33,8 @@ export class CoreGetFallbackLangFromJsonService implements CoreGetFallbackLangSe
   }
 
   onApplicationBootstrap(): void {
-    this.init();
+    // Fire-and-forget: get() already falls back to calling init() inline (line 22) when the
+    // cache has not been populated yet, so a request racing this warm-up still resolves.
+    void this.init();
   }
 }

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

@@ -1,9 +1,9 @@
-import { CoreLang } from '@api/graphql';
+import { CoreLang } from '@api/graphql.js';
 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';
+import { coreLangs } from './core-langs.js';
 
 @Injectable()
 export class CoreGetLangsFromJsonService implements CoreGetLangsService {

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

@@ -1,4 +1,4 @@
-import { CoreLang, CoreLangDir } from '@api/graphql';
+import { CoreLang, CoreLangDir } from '@api/graphql.js';
 
 export const coreLangs: CoreLang[] = [
   {

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

@@ -1,3 +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';
+export { CoreGetFallbackLangFromJsonService } from './core-get-fallback-lang-from-json.service.js';
+export { CoreGetLangsFromJsonService } from './core-get-langs-from-json.service.js';
+export { coreLangs } from './core-langs.js';

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

@@ -1,2 +1,2 @@
-export { MailerCLientModule } from './mailer-client.module';
-export { MailerSMTPTransportService } from './mailer-smtp-transport.service';
+export { MailerCLientModule } from './mailer-client.module.js';
+export { MailerSMTPTransportService } from './mailer-smtp-transport.service.js';

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

@@ -19,10 +19,10 @@ import { DynamicModule } from '@nestjs/common';
 // 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', () => {
+vi.mock('@nestjs-modules/mailer', () => {
   return {
     MailerModule: {
-      forRootAsync: jest.fn((opts: { useFactory?: (...args: unknown[]) => unknown }) => {
+      forRootAsync: vi.fn((opts: { useFactory?: (...args: unknown[]) => unknown }) => {
         if (opts?.useFactory) {
           capturedFactory = opts.useFactory;
         }
@@ -32,22 +32,25 @@ jest.mock('@nestjs-modules/mailer', () => {
   };
 });
 
-jest.mock('nestjs-i18n', () => {
+vi.mock('nestjs-i18n', () => {
   const AcceptLanguageResolver = class {};
   const QueryResolver = class {};
   const I18nModule = {
-    forRoot: jest.fn(() => ({ module: class MockI18nModule {} })),
+    forRoot: vi.fn(() => ({ module: class MockI18nModule {} })),
   };
   return { AcceptLanguageResolver, QueryResolver, I18nModule, I18nService: class {} };
 });
 
-jest.mock('@config/mailer', () => ({
+vi.mock('@config/mailer/index.js', () => ({
   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 {
+// Import the module under test AFTER the mocks are registered by vi.mock() (which is hoisted).
+// A dynamic import, not a static one: `require('./x')` (no extension) does not resolve a
+// TypeScript file under Vitest — its require shim only tries the Node CJS extensions
+// (.js/.json/.node), not .ts, unlike ts-jest's moduleFileExtensions. Top-level await is
+// legal here because Vitest evaluates spec files as ES modules.
+const { MailerCLientModule } = (await import('./mailer-client.module.js')) as {
   MailerCLientModule: { forRootAsync: () => DynamicModule };
 };
 
@@ -56,7 +59,7 @@ describe('MailerCLientModule.forRootAsync()', () => {
 
   beforeEach(() => {
     capturedFactory = undefined;
-    jest.clearAllMocks();
+    vi.clearAllMocks();
   });
 
   afterAll(() => {
@@ -113,10 +116,10 @@ describe('MailerCLientModule.forRootAsync()', () => {
 
       expect(capturedFactory).toBeDefined();
 
-      const mockConfigService = { get: jest.fn().mockReturnValue('noreply@example.com') };
-      const mockI18nService = { t: jest.fn((key: string) => key) };
+      const mockConfigService = { get: vi.fn().mockReturnValue('noreply@example.com') };
+      const mockI18nService = { t: vi.fn((key: string) => key) };
       const mockMailerTransportService = {
-        getTransport: jest.fn().mockReturnValue({ host: 'smtp.example.com' }),
+        getTransport: vi.fn().mockReturnValue({ host: 'smtp.example.com' }),
       };
 
       const config = capturedFactory(
@@ -131,16 +134,16 @@ describe('MailerCLientModule.forRootAsync()', () => {
       expect(adapter).toBeInstanceOf(MjmlAdapter);
     });
 
-    it('invokes the wired t helper (backed by I18nService) when a template renders {{t}}', (done) => {
+    it('invokes the wired t helper (backed by I18nService) when a template renders {{t}}', async () => {
       MailerCLientModule.forRootAsync();
 
       expect(capturedFactory).toBeDefined();
 
-      const i18nSpy = jest.fn((_key: string, _opts?: unknown) => 'TRANSLATED');
+      const i18nSpy = vi.fn((_key: string, _opts?: unknown) => 'TRANSLATED');
       const config = capturedFactory(
-        { get: jest.fn().mockReturnValue('noreply@example.com') },
+        { get: vi.fn().mockReturnValue('noreply@example.com') },
         { t: i18nSpy },
-        { getTransport: jest.fn().mockReturnValue({ host: 'smtp.example.com' }) },
+        { getTransport: vi.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 } } =
@@ -156,23 +159,28 @@ describe('MailerCLientModule.forRootAsync()', () => {
           },
         };
 
-      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 } },
-      );
+      // MjmlAdapter.compile() takes a Node-style (err, ...) callback, not a Promise — wrapped
+      // here rather than using the test's own `done` parameter: Vitest 4 removed that legacy
+      // Mocha-style API ("done() callback is deprecated, use promise instead").
+      await new Promise<void>((resolve, reject) => {
+        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' }),
+              );
+              resolve();
+            } catch (e) {
+              reject(e as Error);
+            }
+          },
+          { template: { dir: config.template.dir } },
+        );
+      });
     });
   });
 });

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

@@ -1,5 +1,5 @@
 import { MailerTransportService } from '@aurorajs.dev/core-back';
-import { MailerTransportModule } from '@config/mailer';
+import { MailerTransportModule } from '@config/mailer/index.js';
 import { MailerModule, MailerOptions } from '@nestjs-modules/mailer';
 import { MjmlAdapter } from '@nestjs-modules/mailer/adapters/mjml.adapter';
 import { DynamicModule, Module } from '@nestjs/common';
@@ -24,7 +24,7 @@ export class MailerCLientModule {
       };
     }
 
-    const srcPath = join(__dirname, '..', '..', '..');
+    const srcPath = join(import.meta.dirname, '..', '..', '..');
 
     return {
       module: MailerCLientModule,

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

@@ -0,0 +1,7 @@
+// PUBLIC surface of the PDF rendering port. Deliberately does NOT re-export the `pdfmake/`
+// sub-barrel — doing so would drag the `pdfmake` library into every consumer of `@aurora/modules`,
+// since `@aurora/modules/index.ts` re-exports this barrel and `app.module.ts` imports from it
+// (design D2). The adapter is reachable only via the explicit `@aurora/modules/pdf/pdfmake`
+// sub-import, from `@config/pdf` and its own spec.
+export * from './pdf-document.types.js';
+export * from './pdf-renderer.service.js';

package/dist/templates/backend/application/src/@aurora/modules/pdf/pdf-document.types.ts

@@ -0,0 +1,48 @@
+/**
+ * Engine-neutral document definition the PDF rendering port accepts. `PdfContentNode` stays a loose
+ * structural bag rather than a typed mirror of a specific engine's content AST — reinventing that
+ * AST here would build the general document-rendering framework this change's Non-Goals reject for
+ * a single consumer. The adapter is the only place that knows how a node maps onto its engine.
+ */
+export type PdfContentNode = Record<string, unknown>;
+
+/** What a header/footer builder knows about its position in the document — nothing else. */
+export interface PdfHeaderFooterContext {
+  currentPage: number;
+  pageCount: number;
+}
+
+export type PdfHeaderFooterBuilder = (context: PdfHeaderFooterContext) => PdfContentNode;
+
+/** `[left, top, right, bottom]`, in points. */
+export type PdfPageMargins = [number, number, number, number];
+
+/**
+ * `images` maps a logical name a content node references (e.g. `{ image: 'logo' }`) to an asset
+ * path RELATIVE to the backend's `assets/` folder (e.g. `pdf/bipdrive-logo.jpg`) — never a data URI
+ * and never an absolute path. Resolving that path to bytes at render time, and failing loudly when
+ * it is missing, is the adapter's job (backend-pdf-rendering spec, "Document assets ship with the
+ * build").
+ */
+export interface PdfDocumentDefinition {
+  content: PdfContentNode[];
+  header?: PdfHeaderFooterBuilder;
+  footer?: PdfHeaderFooterBuilder;
+  images?: Record<string, string>;
+  defaultStyle?: Record<string, unknown>;
+  /**
+   * Named style dictionary a content node references via `{ style: '<name>' }` instead of repeating
+   * its properties inline. Forwarded as-is to the engine (mirrors `defaultStyle`'s pass-through
+   * shape) — the port stays engine-neutral because a style is just another property bag, the same
+   * contract `PdfContentNode` already has.
+   */
+  styles?: Record<string, unknown>;
+  /**
+   * A `header`/`footer` builder renders inside an UNBREAKABLE block confined to exactly
+   * `pageMargins.top`/`.bottom` (pdfmake's `LayoutBuilder.addHeadersAndFooters`) — content taller
+   * than that margin is not reflowed, it overlaps the body. The engine's own default is a flat
+   * `40` on every side, which is too small for a caller whose header carries a logo. Omitting this
+   * leaves the caller with no way to reserve the room its own header/footer needs.
+   */
+  pageMargins?: PdfPageMargins;
+}

package/dist/templates/backend/application/src/@aurora/modules/pdf/pdf-isolation.spec.ts

@@ -0,0 +1,17 @@
+// Barrel-isolation invariant (design D2, `catalyst-provider-composition`): the PDF port's PUBLIC
+// barrel must NEVER pull `pdfmake` into the module graph. Only the intra-module `pdfmake/`
+// sub-barrel — and `@config/pdf`, the intentional composition seam — may reach the library. This
+// test fails LOUDLY if a future edit re-exports the adapter from the port's own barrel, by making
+// the library throw the instant anything requires it.
+vi.mock('pdfmake', () => {
+  throw new Error("pdfmake must not be reachable through the PDF port's public barrel");
+});
+
+describe('@aurora/modules/pdf stays pdfmake-free', () => {
+  // Dynamic import, not require(): Vitest's require shim only resolves the Node CJS
+  // extensions (.js/.json/.node) and does not know the `@aurora` path alias — that is a
+  // vite-tsconfig-paths/esbuild concern that only a real `import()` goes through.
+  it('does not pull pdfmake when importing the port barrel', async () => {
+    await expect(import('@aurora/modules/pdf/index.js')).resolves.toBeDefined();
+  });
+});

package/dist/templates/backend/application/src/@aurora/modules/pdf/pdf-renderer.service.ts

@@ -0,0 +1,12 @@
+import { PdfDocumentDefinition } from './pdf-document.types.js';
+
+/**
+ * The platform's single PDF rendering port (HR-PORTS-001). An abstract class doubles as the DI
+ * token `@config/pdf` binds to one concrete implementation — the same shape `@aurora/modules/mailer`
+ * uses for `MailerTransportService`. The port speaks document structure only, never a bounded
+ * context's own aggregates: a caller hands it a `PdfDocumentDefinition` and gets a buffer back, with
+ * no rendering library appearing anywhere in its own imports or types.
+ */
+export abstract class PdfRendererService {
+  abstract render(document: PdfDocumentDefinition): Promise<Buffer>;
+}

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

@@ -0,0 +1,5 @@
+// PUBLIC SUB-BARREL: the adapter, and only the adapter (HR-BARRELS-004). Importable ONLY from
+// `@config/pdf` (the composition point) and this adapter's own spec — never from `@app/<bc>/**` or
+// from the top-level `@aurora/modules/pdf` barrel, which would defeat the isolation this sub-barrel
+// exists to enforce.
+export { PdfmakeRendererService } from './pdfmake-renderer.service.js';