@stjoseph/prumo 0.0.5 → 0.1.0

package/templates/api/src/infra/http/hooks/auth.hook.ts

@@ -0,0 +1,32 @@
+import { fromNodeHeaders } from 'better-auth/node'
+import type { FastifyInstance, FastifyRequest } from 'fastify'
+import { AUTH, type Auth, type AuthUser } from '@/infra/auth/auth.factory'
+import { HttpError } from '@/infra/http/errors/http-error'
+
+export function registerAuthHook(app: FastifyInstance): void {
+  const auth = app.container.resolve<Auth>(AUTH)
+
+  app.addHook('preHandler', async (request) => {
+    // An unknown route answers 404, not 401: there is nothing there to protect.
+    if (request.is404) {
+      return
+    }
+
+    const session = await auth.api.getSession({ headers: fromNodeHeaders(request.headers) })
+
+    request.user = session?.user
+    request.session = session?.session
+
+    if (request.routeOptions.config.public !== true && session === null) {
+      throw new HttpError(401, 'Unauthorized')
+    }
+  })
+}
+
+export function currentUser(request: FastifyRequest): AuthUser {
+  if (request.user === undefined) {
+    throw new HttpError(401, 'Unauthorized')
+  }
+
+  return request.user
+}

package/templates/api/src/infra/http/hooks/request-context.hook.ts

@@ -0,0 +1,9 @@
+import { type EntityManager, RequestContext } from '@mikro-orm/postgresql'
+import type { FastifyInstance } from 'fastify'
+
+export function registerRequestContext(app: FastifyInstance, em: EntityManager): void {
+  app.addHook('onRequest', (request, reply, done) => {
+    reply.header('x-request-id', request.id)
+    RequestContext.create(em, done)
+  })
+}

package/templates/api/src/infra/http/server.ts

@@ -0,0 +1,34 @@
+// tsyringe reads decorator metadata as each class is loaded, so this must come before any other import.
+import 'reflect-metadata'
+import { MikroORM } from '@mikro-orm/postgresql'
+import type { Pool } from 'pg'
+import { AUTH, type Auth } from '@/infra/auth/auth.factory'
+import { loadEnv } from '@/infra/config/env'
+import { createOrmConfig } from '@/infra/database/mikroorm/mikro-orm.factory'
+import { createContainer } from '@/infra/di'
+import { buildApp } from './app'
+
+async function main(): Promise<void> {
+  const env = loadEnv()
+  const orm = await MikroORM.init(createOrmConfig(env))
+
+  // MikroORM 7 no longer connects on init, so readiness would report the database down until a first query.
+  await orm.connect()
+
+  const container = createContainer({ env, orm })
+  const app = await buildApp(container)
+
+  // Handling the signals takes away Node's default exit, so every open pool must close for the process to end.
+  app.addHook('onClose', async () => {
+    await orm.close()
+    await (container.resolve<Auth>(AUTH).options.database as Pool).end()
+  })
+
+  for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+    process.once(signal, () => void app.close())
+  }
+
+  await app.listen({ port: env.PORT, host: '::' })
+}
+
+void main()

package/templates/api/src/infra/mcp/mcp.server.ts

@@ -0,0 +1,20 @@
+import { createMcpHandler, type McpHttpHandler, McpServer } from '@modelcontextprotocol/server'
+import type { DependencyContainer } from 'tsyringe'
+import { registerUserTools } from './tools/users.tool'
+
+// One server per request: the protocol is stateless, and each instance knows only its caller.
+export function createMcpServerHandler(container: DependencyContainer): McpHttpHandler {
+  return createMcpHandler(
+    ({ authInfo }) => {
+      const server = new McpServer({ name: 'api', version: '1.0.0' })
+      const userId = authInfo?.extra?.userId
+
+      if (typeof userId === 'string') {
+        registerUserTools(server, container, userId)
+      }
+
+      return server
+    },
+    { legacy: 'reject' },
+  )
+}

package/templates/api/src/infra/mcp/tools/users.tool.ts

@@ -0,0 +1,39 @@
+import type { McpServer } from '@modelcontextprotocol/server'
+import type { DependencyContainer } from 'tsyringe'
+import { profileResponseSchema } from '@/domain/users/dto/profile-response.dto'
+import { updateProfileSchema } from '@/domain/users/dto/update-profile.dto'
+import type { Profile } from '@/domain/users/entities/profile.entity'
+import { FindProfileUseCase } from '@/domain/users/use-cases/find-profile.use-case'
+import { UpdateProfileUseCase } from '@/domain/users/use-cases/update-profile.use-case'
+
+// MCP sends whatever a tool returns, so the output schema is applied here: nothing drops unlisted fields.
+function asResult(profile: Profile) {
+  const data = JSON.parse(JSON.stringify(profileResponseSchema.parse(profile)))
+
+  return {
+    content: [{ type: 'text' as const, text: JSON.stringify(data) }],
+    structuredContent: data,
+  }
+}
+
+export function registerUserTools(
+  server: McpServer,
+  container: DependencyContainer,
+  userId: string,
+): void {
+  server.registerTool(
+    'get_profile',
+    { description: "Read the signed-in user's profile." },
+    async () => asResult(await container.resolve(FindProfileUseCase).execute(userId)),
+  )
+
+  server.registerTool(
+    'update_profile',
+    {
+      description: "Change the signed-in user's display name, locale or timezone.",
+      inputSchema: updateProfileSchema,
+    },
+    async (changes) =>
+      asResult(await container.resolve(UpdateProfileUseCase).execute(userId, changes)),
+  )
+}

package/templates/api/test/domain/users/use-cases/find-profile.use-case.spec.ts

@@ -0,0 +1,22 @@
+import { InMemoryProfileRepository } from '@test/support/fakes/in-memory-profile.repository'
+import { describe, expect, it } from 'vitest'
+import { Profile } from '@/domain/users/entities/profile.entity'
+import { ProfileNotFoundError } from '@/domain/users/errors/profile-not-found.error'
+import { FindProfileUseCase } from '@/domain/users/use-cases/find-profile.use-case'
+
+describe('FindProfileUseCase', () => {
+  it('finds the profile belonging to a user', async () => {
+    const profiles = new InMemoryProfileRepository()
+    await profiles.save(new Profile('user-1', 'Ana'))
+
+    await expect(new FindProfileUseCase(profiles).execute('user-1')).resolves.toMatchObject({
+      displayName: 'Ana',
+    })
+  })
+
+  it('refuses a user without a profile', async () => {
+    const findProfile = new FindProfileUseCase(new InMemoryProfileRepository())
+
+    await expect(findProfile.execute('nobody')).rejects.toBeInstanceOf(ProfileNotFoundError)
+  })
+})

package/templates/api/test/domain/users/use-cases/update-profile.use-case.spec.ts

@@ -0,0 +1,26 @@
+import { InMemoryProfileRepository } from '@test/support/fakes/in-memory-profile.repository'
+import { describe, expect, it } from 'vitest'
+import { Profile } from '@/domain/users/entities/profile.entity'
+import { ProfileNotFoundError } from '@/domain/users/errors/profile-not-found.error'
+import { UpdateProfileUseCase } from '@/domain/users/use-cases/update-profile.use-case'
+
+describe('UpdateProfileUseCase', () => {
+  it('applies only the fields the request carries', async () => {
+    const profiles = new InMemoryProfileRepository()
+    const profile = new Profile('user-1', 'Ana')
+    profile.update({ timezone: 'UTC' })
+    await profiles.save(profile)
+
+    const updated = await new UpdateProfileUseCase(profiles).execute('user-1', {
+      timezone: 'America/Sao_Paulo',
+    })
+
+    expect(updated).toMatchObject({ displayName: 'Ana', timezone: 'America/Sao_Paulo' })
+  })
+
+  it('refuses a user without a profile', async () => {
+    const updateProfile = new UpdateProfileUseCase(new InMemoryProfileRepository())
+
+    await expect(updateProfile.execute('nobody', {})).rejects.toBeInstanceOf(ProfileNotFoundError)
+  })
+})

package/templates/api/{src → test/infra}/auth/auth.factory.spec.ts

@@ -1,26 +1,19 @@
+import { testEnv } from '@test/support/setup'
 import { describe, expect, it } from 'vitest'
-import { testDatabaseUrl } from '../../test/setup'
-import { createAuth } from './auth.factory'
-
-const env = () => ({
-  AUTH_DATABASE_URL: testDatabaseUrl(),
-  BETTER_AUTH_SECRET: 'test-secret-that-is-at-least-32-characters',
-  BETTER_AUTH_URL: 'http://localhost:3000',
-  WEB_ORIGIN: 'http://localhost:5173',
-})
+import { createAuth } from '@/infra/auth/auth.factory'
 
 const proxy =
   'http://localhost:3000/api/auth/expo-authorization-proxy?authorizationURL=https://example.com/authorize&oauthState=s'
 
 describe('createAuth', () => {
   it('exposes no Expo redirect endpoint without a mobile scheme', async () => {
-    const response = await createAuth(env()).handler(new Request(proxy))
+    const response = await createAuth(testEnv()).handler(new Request(proxy))
 
     expect(response.status).toBe(404)
   })
 
   it('exposes the Expo endpoint and trusts the scheme once a mobile scheme is set', async () => {
-    const auth = createAuth({ ...env(), MOBILE_APP_SCHEME: 'app' })
+    const auth = createAuth({ ...testEnv(), MOBILE_APP_SCHEME: 'app' })
     const response = await auth.handler(new Request(proxy))
 
     expect(response.status).toBe(302)

package/templates/api/test/infra/database/mikroorm/mikro-orm.factory.spec.ts

@@ -0,0 +1,8 @@
+import { testOrm } from '@test/support/setup'
+import { describe, expect, it } from 'vitest'
+
+describe('createOrmConfig', () => {
+  it('finds nothing to change once migrated, and leaves Better Auth’s schema alone', async () => {
+    await expect(testOrm().schema.getUpdateSchemaSQL({ wrap: false })).resolves.toBe('')
+  })
+})

package/templates/api/test/infra/database/mikroorm/repositories/mikroorm-profile.repository.spec.ts

@@ -0,0 +1,51 @@
+import { createProfile } from '@test/support/factories/profile.factory'
+import { createUser } from '@test/support/factories/user.factory'
+import { testOrm } from '@test/support/setup'
+import { describe, expect, it } from 'vitest'
+import { Profile } from '@/domain/users/entities/profile.entity'
+import { MikroOrmProfileRepository } from '@/infra/database/mikroorm/repositories/mikroorm-profile.repository'
+
+describe('MikroOrmProfileRepository', () => {
+  it('finds a profile by its user', async () => {
+    const created = await createProfile(testOrm().em.fork(), { displayName: 'Ana' })
+    const profiles = new MikroOrmProfileRepository(testOrm().em.fork())
+
+    const found = await profiles.findByUserId(created.userId)
+
+    expect(found).toBeInstanceOf(Profile)
+    expect(found).toMatchObject({ displayName: 'Ana' })
+  })
+
+  it('answers null for a user without a profile', async () => {
+    const profiles = new MikroOrmProfileRepository(testOrm().em.fork())
+
+    await expect(profiles.findByUserId(crypto.randomUUID())).resolves.toBeNull()
+  })
+
+  it('lets the database fill the id, the defaults and the timestamps', async () => {
+    const userId = await createUser(testOrm().em.fork())
+    await new MikroOrmProfileRepository(testOrm().em.fork()).save(new Profile(userId, 'Ana'))
+
+    const stored = await new MikroOrmProfileRepository(testOrm().em.fork()).findByUserId(userId)
+
+    expect(stored).toMatchObject({ locale: 'en', timezone: 'UTC' })
+    // uuidv7() puts the version nibble at the start of the third group.
+    expect(stored?.id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-7/)
+    expect(stored?.createdAt).toBeInstanceOf(Date)
+  })
+
+  it('writes what the entity changed', async () => {
+    const created = await createProfile(testOrm().em.fork(), { timezone: 'UTC' })
+    const profiles = new MikroOrmProfileRepository(testOrm().em.fork())
+    const profile = await profiles.findByUserId(created.userId)
+
+    profile?.update({ timezone: 'America/Sao_Paulo' })
+    await profiles.save(profile as Profile)
+
+    const reloaded = await new MikroOrmProfileRepository(testOrm().em.fork()).findByUserId(
+      created.userId,
+    )
+
+    expect(reloaded?.timezone).toBe('America/Sao_Paulo')
+  })
+})

package/templates/api/test/infra/database/mikroorm/transactions/mikroorm-transaction-manager.spec.ts

@@ -0,0 +1,29 @@
+import { RequestContext } from '@mikro-orm/postgresql'
+import { createUser } from '@test/support/factories/user.factory'
+import { testOrm } from '@test/support/setup'
+import { describe, expect, it } from 'vitest'
+import { Profile } from '@/domain/users/entities/profile.entity'
+import { MikroOrmProfileRepository } from '@/infra/database/mikroorm/repositories/mikroorm-profile.repository'
+import { MikroOrmTransactionManager } from '@/infra/database/mikroorm/transactions/mikroorm-transaction-manager'
+
+describe('MikroOrmTransactionManager', () => {
+  it('rolls back every write inside run() when one of them fails', async () => {
+    const orm = testOrm()
+    const userId = await createUser(orm.em.fork())
+
+    // The same wiring as a request: the global EntityManager, resolved through a request context.
+    await RequestContext.create(orm.em, async () => {
+      const transactions = new MikroOrmTransactionManager(orm.em)
+      const profiles = new MikroOrmProfileRepository(orm.em)
+
+      await expect(
+        transactions.run(async () => {
+          await profiles.save(new Profile(userId, 'first'))
+          await profiles.save(new Profile(userId, 'same user, refused by the unique constraint'))
+        }),
+      ).rejects.toThrow()
+    })
+
+    expect(await orm.em.fork().count(Profile)).toBe(0)
+  })
+})

package/templates/api/test/infra/http/app.spec.ts

@@ -0,0 +1,21 @@
+import { testEnv, testOrm } from '@test/support/setup'
+import { describe, expect, it } from 'vitest'
+import { createContainer } from '@/infra/di'
+import { buildApp } from '@/infra/http/app'
+
+describe('buildApp', () => {
+  it('refuses a versioned route that declares no response schema', async () => {
+    const app = await buildApp(createContainer({ env: testEnv(), orm: testOrm() }))
+
+    await expect(
+      app.register(
+        async (scope) => {
+          scope.get('/leak', async () => ({ secret: true }))
+        },
+        { prefix: '/api/v1' },
+      ),
+    ).rejects.toThrow('GET /api/v1/leak declares no response schema')
+
+    await app.close()
+  })
+})

package/templates/api/test/infra/http/controllers/mcp.controller.spec.ts

@@ -0,0 +1,152 @@
+import { createHash, randomBytes } from 'node:crypto'
+import { createServer } from 'node:net'
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'
+import { testEnv, testOrm } from '@test/support/setup'
+import type { FastifyInstance } from 'fastify'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { mcpResource } from '@/infra/auth/auth.factory'
+import { createContainer } from '@/infra/di'
+import { buildApp } from '@/infra/http/app'
+
+const ORIGIN = 'http://localhost:5173'
+// A web client needs an https redirect off loopback; the test never follows it.
+const REDIRECT = 'https://client.example.com/callback'
+
+let app: FastifyInstance
+let env: ReturnType<typeof testEnv>
+
+function freePort(): Promise<number> {
+  return new Promise((resolve) => {
+    const server = createServer().listen(0, '127.0.0.1', () => {
+      const { port } = server.address() as { port: number }
+      server.close(() => resolve(port))
+    })
+  })
+}
+
+// requireMcpAuth fetches the JWKS from BETTER_AUTH_URL, so the application listens for real.
+beforeEach(async () => {
+  const port = await freePort()
+  env = { ...testEnv(), BETTER_AUTH_URL: `http://127.0.0.1:${port}` }
+  app = await buildApp(createContainer({ env, orm: testOrm() }))
+  await app.listen({ port, host: '127.0.0.1' })
+})
+
+afterEach(async () => {
+  await app.close()
+})
+
+async function signUp(): Promise<string> {
+  const response = await app.inject({
+    method: 'POST',
+    url: '/api/auth/sign-up/email',
+    headers: { origin: ORIGIN },
+    payload: {
+      name: 'Ana',
+      email: `${crypto.randomUUID()}@example.com`,
+      password: 'correct-horse-battery',
+    },
+  })
+  const cookies = [response.headers['set-cookie']].flat().filter((c) => c !== undefined)
+
+  return cookies.map((cookie) => cookie.split(';')[0]).join('; ')
+}
+
+// The path an MCP client takes: register, authorize with PKCE, consent, exchange the code.
+async function accessToken(cookie: string): Promise<string> {
+  const client = await app.inject({
+    method: 'POST',
+    url: '/api/auth/oauth2/create-client',
+    headers: { cookie, origin: ORIGIN },
+    payload: { redirect_uris: [REDIRECT], token_endpoint_auth_method: 'none' },
+  })
+  const clientId = client.json().client_id as string
+  const verifier = randomBytes(32).toString('base64url')
+  const query = new URLSearchParams({
+    response_type: 'code',
+    client_id: clientId,
+    redirect_uri: REDIRECT,
+    scope: 'openid',
+    state: 'state',
+    code_challenge: createHash('sha256').update(verifier).digest('base64url'),
+    code_challenge_method: 'S256',
+    resource: mcpResource(env),
+  })
+  const authorize = await app.inject({
+    url: `/api/auth/oauth2/authorize?${query}`,
+    headers: { cookie },
+  })
+  const consentPage = new URL(authorize.headers.location as string)
+  const consent = await app.inject({
+    method: 'POST',
+    url: '/api/auth/oauth2/consent',
+    headers: { cookie, origin: ORIGIN },
+    payload: { accept: true, oauth_query: consentPage.search.slice(1) },
+  })
+  const redirect = new URL(consent.json().url ?? consent.json().redirect_uri)
+  const token = await app.inject({
+    method: 'POST',
+    url: '/api/auth/oauth2/token',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    payload: new URLSearchParams({
+      grant_type: 'authorization_code',
+      code: redirect.searchParams.get('code') ?? '',
+      redirect_uri: REDIRECT,
+      client_id: clientId,
+      code_verifier: verifier,
+      resource: mcpResource(env),
+    }).toString(),
+  })
+
+  return token.json().access_token as string
+}
+
+// The SDK's own client, speaking the real protocol over HTTP.
+async function connect(token: string): Promise<Client> {
+  // The server rejects 2025-era traffic, as Better Auth's MCP profile asks.
+  const client = new Client(
+    { name: 'test', version: '1.0.0' },
+    { versionNegotiation: { mode: { pin: '2026-07-28' } } },
+  )
+
+  await client.connect(
+    new StreamableHTTPClientTransport(new URL(mcpResource(env)), {
+      requestInit: { headers: { authorization: `Bearer ${token}` } },
+    }),
+  )
+  return client
+}
+
+describe('mcp controller', () => {
+  it('tells an MCP client where to authorize', async () => {
+    const metadata = await app.inject({ url: '/.well-known/oauth-protected-resource' })
+    const refused = await app.inject({ method: 'POST', url: '/api/mcp', payload: {} })
+
+    expect(metadata.json()).toMatchObject({ resource: mcpResource(env) })
+    expect(refused.statusCode).toBe(401)
+    expect(refused.headers['www-authenticate']).toContain('resource_metadata=')
+  })
+
+  it('runs a tool for the user who authorized the client, with public fields only', async () => {
+    const client = await connect(await accessToken(await signUp()))
+    const result = await client.callTool({ name: 'get_profile', arguments: {} })
+    expect(Object.keys(result.structuredContent ?? {}).sort()).toEqual(
+      ['createdAt', 'displayName', 'id', 'locale', 'timezone', 'updatedAt', 'userId'].sort(),
+    )
+    expect(result.structuredContent).toMatchObject({ displayName: 'Ana' })
+
+    await client.close()
+  })
+
+  it('changes the profile through a tool', async () => {
+    const client = await connect(await accessToken(await signUp()))
+    const result = await client.callTool({
+      name: 'update_profile',
+      arguments: { timezone: 'America/Sao_Paulo' },
+    })
+
+    expect(result.structuredContent).toMatchObject({ timezone: 'America/Sao_Paulo' })
+
+    await client.close()
+  })
+})

package/templates/api/test/infra/http/controllers/users.controller.spec.ts

@@ -0,0 +1,105 @@
+import { testEnv, testOrm } from '@test/support/setup'
+import type { FastifyInstance } from 'fastify'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { createContainer } from '@/infra/di'
+import { buildApp } from '@/infra/http/app'
+
+const ORIGIN = 'http://localhost:5173'
+
+let app: FastifyInstance
+
+async function signUp(): Promise<string[]> {
+  const response = await app.inject({
+    method: 'POST',
+    url: '/api/auth/sign-up/email',
+    headers: { origin: ORIGIN },
+    payload: {
+      name: 'Ana',
+      email: `${crypto.randomUUID()}@example.com`,
+      password: 'correct-horse-battery',
+    },
+  })
+
+  expect(response.statusCode).toBe(200)
+
+  const cookies = response.headers['set-cookie']
+  return Array.isArray(cookies) ? cookies : [cookies ?? '']
+}
+
+function cookieHeader(cookies: string[]): string {
+  return cookies.map((cookie) => cookie.split(';')[0]).join('; ')
+}
+
+beforeEach(async () => {
+  app = await buildApp(createContainer({ env: testEnv(), orm: testOrm() }))
+})
+
+afterEach(async () => {
+  await app.close()
+})
+
+describe('users controller', () => {
+  it('refuses /users/me without a session', async () => {
+    const response = await app.inject({ url: '/api/v1/users/me' })
+
+    expect(response.statusCode).toBe(401)
+    expect(response.headers['content-type']).toContain('application/problem+json')
+  })
+
+  it('returns the profile created at sign-up, and only its public fields', async () => {
+    const cookie = cookieHeader(await signUp())
+    const response = await app.inject({ url: '/api/v1/users/me', headers: { cookie } })
+
+    expect(response.statusCode).toBe(200)
+    expect(Object.keys(response.json()).sort()).toEqual(
+      ['createdAt', 'displayName', 'id', 'locale', 'timezone', 'updatedAt', 'userId'].sort(),
+    )
+    expect(response.json()).toMatchObject({ displayName: 'Ana', locale: 'en' })
+  })
+
+  it('updates the profile', async () => {
+    const cookie = cookieHeader(await signUp())
+    const response = await app.inject({
+      method: 'PATCH',
+      url: '/api/v1/users/me',
+      headers: { cookie, origin: ORIGIN },
+      payload: { timezone: 'America/Sao_Paulo' },
+    })
+
+    expect(response.statusCode).toBe(200)
+    expect(response.json()).toMatchObject({ displayName: 'Ana', timezone: 'America/Sao_Paulo' })
+  })
+
+  it('names every rejected field, including one the schema does not know', async () => {
+    const cookie = cookieHeader(await signUp())
+    const response = await app.inject({
+      method: 'PATCH',
+      url: '/api/v1/users/me',
+      headers: { cookie, origin: ORIGIN },
+      payload: { displayName: '', role: 'admin' },
+    })
+
+    expect(response.statusCode).toBe(400)
+    expect(response.json()).toMatchObject({
+      status: 400,
+      errors: { displayName: [expect.any(String)], role: ['Unrecognized key'] },
+    })
+  })
+
+  it('signs out', async () => {
+    const cookie = cookieHeader(await signUp())
+    const response = await app.inject({
+      method: 'POST',
+      url: '/api/auth/sign-out',
+      headers: { cookie, origin: ORIGIN },
+    })
+
+    expect(response.statusCode).toBe(200)
+  })
+
+  it('answers an unknown route with 404, not 401', async () => {
+    const response = await app.inject({ url: '/api/v1/nothing-here' })
+
+    expect(response.statusCode).toBe(404)
+  })
+})

package/templates/api/test/support/factories/profile.factory.ts

@@ -0,0 +1,25 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createUser } from '@test/support/factories/user.factory'
+import { type Locale, Profile } from '@/domain/users/entities/profile.entity'
+
+type ProfileOverrides = Partial<{
+  userId: string
+  displayName: string
+  locale: Locale
+  timezone: string
+}>
+
+export async function createProfile(
+  em: EntityManager,
+  overrides: ProfileOverrides = {},
+): Promise<Profile> {
+  const profile = new Profile(
+    overrides.userId ?? (await createUser(em)),
+    overrides.displayName ?? 'Test Person',
+  )
+
+  profile.update({ locale: overrides.locale ?? 'en', timezone: overrides.timezone ?? 'UTC' })
+  await em.persist(profile).flush()
+
+  return profile
+}

package/templates/api/test/{factories → support/factories}/user.factory.ts

@@ -9,7 +9,7 @@ export async function createUser(
 ): Promise<string> {
   const id = randomUUID()
 
-  // auth.user belongs to Better Auth and has no entity here, so the QueryBuilder cannot reach it.
+  // auth.user belongs to Better Auth, and the ORM maps only its id, so the row is written in SQL.
   await em
     .getConnection()
     .execute(

package/templates/api/test/support/fakes/in-memory-profile.repository.ts

@@ -0,0 +1,14 @@
+import type { Profile } from '@/domain/users/entities/profile.entity'
+import type { ProfileRepository } from '@/domain/users/repositories/profile.repository'
+
+export class InMemoryProfileRepository implements ProfileRepository {
+  readonly rows = new Map<string, Profile>()
+
+  async findByUserId(userId: string): Promise<Profile | null> {
+    return this.rows.get(userId) ?? null
+  }
+
+  async save(profile: Profile): Promise<void> {
+    this.rows.set(profile.userId, profile)
+  }
+}