@stjoseph/prumo 0.0.6 → 0.1.0

package/templates/web/vite.config.ts

@@ -6,13 +6,13 @@ import { defineConfig } from 'vitest/config'
 export default defineConfig({
   plugins: [tanstackRouter({ target: 'react', autoCodeSplitting: true }), react(), tailwindcss()],
   resolve: {
-    alias: { '@': `${import.meta.dirname}/src` },
+    alias: { '@': `${import.meta.dirname}/src`, '@test': `${import.meta.dirname}/test` },
   },
   test: {
     environment: 'jsdom',
     globals: true,
-    include: ['src/**/*.spec.{ts,tsx}'],
-    setupFiles: ['./test/setup.ts'],
+    include: ['test/**/*.spec.{ts,tsx}'],
+    setupFiles: ['./test/support/setup.ts'],
     coverage: { provider: 'v8', include: ['src/**'] },
   },
 })

package/.prumo-templates/api/modules.md

@@ -1,117 +0,0 @@
-# Modules
-
-## Rule
-
-Create one module per resource: `users`, `orders`, `invoices`.
-
-A module contains exactly what `nest g resource` produces: `*.module.ts`, `*.controller.ts`,
-`*.service.ts`, `dto/`, `entities/` and the co-located spec files. Add nothing to that set, **except further
-services**.
-
-Add a service to a module when a group of its methods has a name of its own that the resource's name does
-not cover: `order-refunds`, `order-shipping`. Generate it with `nest g service <name> <module> --flat`, beside
-the resource's service. Do not split by line count, and do not create a `services/` directory or one service
-per action.
-
-Two services in one module never inject each other in both directions.
-
-Export the service. Mark every method that serves only its own module `private`.
-
-Reach another module through `imports: [OtherModule]` and inject what it exports. Reference another
-module's entity when a relation requires it.
-
-Two modules never depend on each other. When they appear to, move the common part into a third
-module. Do not use `forwardRef`.
-
-Do not use barrel files inside a module.
-
-Anything serving more than one module becomes its own module, named for what it does:
-`notifications`, `pdf`, `storage`. There is no `SharedModule`.
-
-A pure function is a function in a file, imported directly. It gets no module.
-
-## Rationale
-
-Nest supplies the mechanism and decides none of this, so every rule above exists to remove a choice
-that would otherwise be made differently in each module and by each assistant.
-
-One module per resource is the shape `nest g resource` generates and the shape every Nest example
-already has, so the generator and the convention never disagree and a generated module needs no
-correction afterwards. Designing an anatomy instead is what previously cost thirteen files per
-feature, five of which carried no guarantee.
-
-`private` makes the compiler enforce the module's surface, at no cost. A cycle is refused because
-Nest's own guidance is to avoid one: `forwardRef` is its escape hatch, and its documented caveats
-include an indeterminate order of instantiation, the class of failure that appears once in
-production and does not reproduce. Barrel files are refused because Nest names them as a way to
-create a cycle nobody can see.
-
-**The extra service exists for the module that is large and still one thing.** Splitting into another
-module is right when a second responsibility has crept in, and wrong when it has not: two modules sharing the
-same entities and invariants end up wanting to call each other, which is the cycle refused above. Nest's own
-answer is several providers in one module, and `nest g service <name> <module>` both creates the file and
-registers it, so the generator and the convention still agree.
-
-The criterion is a name rather than a size because a line limit ages and invites gaming: somebody moves
-arbitrary methods out to pass the number, and the result is worse than the long file. `--flat` keeps the
-anatomy one level deep. One service per action is refused on evidence: it is what produced thirteen files
-per feature.
-
-**What this costs:** the split is a judgement, held by review. And a module with several services can form a
-cycle inside itself, which is why the cycle rule now reaches between services as well as between modules.
-
-A `SharedModule` has no admission criterion, so it only grows. Requiring a name forces the question
-*what is this*, and a module nobody can name should not exist.
-
-## Applies to
-
-Every module under `src/`. The rules about reaching across modules apply wherever one module's code
-refers to another's.
-
-## Examples
-
-Exporting the service, with internals closed:
-
-```
-✅  export class UsersService {
-      findById(id: string) {}
-      private normaliseEmail(v: string) {}
-    }
-
-❌  export class UsersService {
-      findById(id: string) {}
-      normaliseEmail(v: string) {}   // reachable from any module that injects this
-    }
-```
-
-Growing a module that is still one thing:
-
-```
-✅  orders/orders.service.ts
-    orders/order-refunds.service.ts     // nest g service order-refunds orders --flat
-❌  orders/services/cancel-order.service.ts
-❌  refunds/refunds.module.ts           // needs orders' entities, and orders needs it back
-```
-
-Reaching another module:
-
-```
-✅  @Module({ imports: [UsersModule] })
-❌  @Module({ imports: [forwardRef(() => UsersModule)] })
-```
-
-Importing inside a module:
-
-```
-✅  import { UsersService } from './users.service'
-❌  import { UsersService } from './index'
-```
-
-## Enforcement
-
-**Lint.** Barrel-file imports inside a module are verifiable and are caught by a lint rule.
-
-**Review only.** Everything else. Nothing checks that a module maps to a resource, that an extra service
-has a name of its own rather than an arbitrary slice, that a method that
-should be `private` is, or that a `SharedModule` has not been created; a reviewer does. `private`
-prevents accidental injection; it does not prevent someone widening the method next week to reach it.

package/templates/api/nest-cli.json

@@ -1,10 +0,0 @@
-{
-  "$schema": "https://json.schemastore.org/nest-cli",
-  "collection": "@nestjs/schematics",
-  "sourceRoot": "src",
-  "compilerOptions": {
-    "deleteOutDir": true,
-    "tsConfigPath": "tsconfig.build.json",
-    "plugins": ["@nestjs/swagger/plugin"]
-  }
-}

package/templates/api/src/app.module.ts

@@ -1,46 +0,0 @@
-import { MikroOrmModule } from '@mikro-orm/nestjs'
-import { PostgreSqlDriver } from '@mikro-orm/postgresql'
-import { type MiddlewareConsumer, Module, type NestModule } from '@nestjs/common'
-import { APP_FILTER } from '@nestjs/core'
-import { LoggerModule } from 'nestjs-pino'
-import { AuthModule } from '@/auth/auth.module'
-import { Env } from '@/config/env'
-import { EnvModule } from '@/config/env.module'
-import { ProblemDetailsFilter } from '@/errors/problem-details.filter'
-import { HealthModule } from '@/health/health.module'
-import { createOrmConfig } from '@/mikro-orm.factory'
-import { RequestContextModule } from '@/request-context/request-context.module'
-import { RequestIdMiddleware } from '@/request-context/request-id.middleware'
-import { UsersModule } from '@/users/users.module'
-
-@Module({
-  imports: [
-    EnvModule,
-    LoggerModule.forRootAsync({
-      inject: [Env],
-      useFactory: (env: Env) => ({
-        pinoHttp: {
-          level: env.LOG_LEVEL,
-          redact: ['req.headers.authorization', 'req.headers.cookie', 'res.headers["set-cookie"]'],
-          transport: env.NODE_ENV === 'development' ? { target: 'pino-pretty' } : undefined,
-          autoLogging: { ignore: (req) => req.url?.startsWith('/api/health') === true },
-        },
-      }),
-    }),
-    MikroOrmModule.forRootAsync({
-      inject: [Env],
-      driver: PostgreSqlDriver,
-      useFactory: (env: Env) => createOrmConfig(env),
-    }),
-    RequestContextModule,
-    AuthModule,
-    HealthModule,
-    UsersModule,
-  ],
-  providers: [{ provide: APP_FILTER, useClass: ProblemDetailsFilter }],
-})
-export class AppModule implements NestModule {
-  configure(consumer: MiddlewareConsumer): void {
-    consumer.apply(RequestIdMiddleware).forRoutes('*path')
-  }
-}

package/templates/api/src/auth/auth.constants.ts

@@ -1,2 +0,0 @@
-export const AUTH = Symbol('AUTH')
-export const IS_PUBLIC = Symbol('IS_PUBLIC')

package/templates/api/src/auth/auth.controller.ts

@@ -1,19 +0,0 @@
-import { All, Controller, Inject, Req, Res, VERSION_NEUTRAL } from '@nestjs/common'
-import { ApiExcludeController } from '@nestjs/swagger'
-import { toNodeHandler } from 'better-auth/node'
-import type { Request, Response } from 'express'
-import { AUTH } from './auth.constants'
-import type { Auth } from './auth.factory'
-import { Public } from './public.decorator'
-
-@ApiExcludeController()
-@Controller({ path: 'auth', version: VERSION_NEUTRAL })
-export class AuthController {
-  constructor(@Inject(AUTH) private readonly auth: Auth) {}
-
-  @Public()
-  @All('*path')
-  handle(@Req() request: Request, @Res() response: Response): Promise<void> {
-    return toNodeHandler(this.auth)(request, response)
-  }
-}

package/templates/api/src/auth/auth.guard.ts

@@ -1,43 +0,0 @@
-import {
-  type CanActivate,
-  type ExecutionContext,
-  Inject,
-  Injectable,
-  UnauthorizedException,
-} from '@nestjs/common'
-import { Reflector } from '@nestjs/core'
-import { fromNodeHeaders } from 'better-auth/node'
-import type { Request } from 'express'
-import { AUTH, IS_PUBLIC } from './auth.constants'
-import type { Auth } from './auth.factory'
-
-@Injectable()
-export class AuthGuard implements CanActivate {
-  constructor(
-    private readonly reflector: Reflector,
-    @Inject(AUTH) private readonly auth: Auth,
-  ) {}
-
-  async canActivate(context: ExecutionContext): Promise<boolean> {
-    const request = context.switchToHttp().getRequest<Request>()
-    const session = await this.auth.api.getSession({ headers: fromNodeHeaders(request.headers) })
-
-    request.user = session?.user
-    request.session = session?.session
-
-    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC, [
-      context.getHandler(),
-      context.getClass(),
-    ])
-
-    if (isPublic === true) {
-      return true
-    }
-
-    if (session === null) {
-      throw new UnauthorizedException()
-    }
-
-    return true
-  }
-}

package/templates/api/src/auth/auth.module.ts

@@ -1,30 +0,0 @@
-import { Global, Module } from '@nestjs/common'
-import { APP_GUARD } from '@nestjs/core'
-import { Env } from '@/config/env'
-import { UsersModule } from '@/users/users.module'
-import { UsersService } from '@/users/users.service'
-import { AUTH } from './auth.constants'
-import { AuthController } from './auth.controller'
-import { createAuth } from './auth.factory'
-import { AuthGuard } from './auth.guard'
-
-@Global()
-@Module({
-  imports: [UsersModule],
-  controllers: [AuthController],
-  providers: [
-    {
-      provide: AUTH,
-      inject: [Env, UsersService],
-      useFactory: (env: Env, users: UsersService) =>
-        createAuth(env, {
-          onUserCreated: async (user) => {
-            await users.createProfile(user.id, user.name)
-          },
-        }),
-    },
-    { provide: APP_GUARD, useClass: AuthGuard },
-  ],
-  exports: [AUTH],
-})
-export class AuthModule {}

package/templates/api/src/auth/auth.ts

@@ -1,4 +0,0 @@
-import { loadEnv } from '@/config/env'
-import { createAuth } from './auth.factory'
-
-export const auth = createAuth(loadEnv())

package/templates/api/src/auth/current-user.decorator.ts

@@ -1,9 +0,0 @@
-import { createParamDecorator, type ExecutionContext } from '@nestjs/common'
-import type { Request } from 'express'
-import type { AuthUser } from './auth.factory'
-
-export const CurrentUser = createParamDecorator(
-  (_data: unknown, context: ExecutionContext): AuthUser | undefined => {
-    return context.switchToHttp().getRequest<Request>().user
-  },
-)

package/templates/api/src/auth/express.d.ts

@@ -1,10 +0,0 @@
-import type { AuthSession, AuthUser } from './auth.factory'
-
-declare global {
-  namespace Express {
-    interface Request {
-      user?: AuthUser
-      session?: NonNullable<AuthSession>['session']
-    }
-  }
-}

package/templates/api/src/auth/public.decorator.ts

@@ -1,4 +0,0 @@
-import { SetMetadata } from '@nestjs/common'
-import { IS_PUBLIC } from './auth.constants'
-
-export const Public = () => SetMetadata(IS_PUBLIC, true)

package/templates/api/src/config/env.module.ts

@@ -1,11 +0,0 @@
-import { Global, Module } from '@nestjs/common'
-import { ConfigModule } from '@nestjs/config'
-import { Env, loadEnv } from './env'
-
-@Global()
-@Module({
-  imports: [ConfigModule.forRoot({ cache: true, ignoreEnvFile: true, validate: loadEnv })],
-  providers: [{ provide: Env, useFactory: loadEnv }],
-  exports: [Env],
-})
-export class EnvModule {}

package/templates/api/src/config/env.ts

@@ -1,81 +0,0 @@
-import 'reflect-metadata'
-import { existsSync } from 'node:fs'
-import { plainToInstance } from 'class-transformer'
-import {
-  IsEnum,
-  IsInt,
-  IsOptional,
-  IsString,
-  Matches,
-  Max,
-  Min,
-  MinLength,
-  validateSync,
-} from 'class-validator'
-
-export type NodeEnv = 'development' | 'test' | 'production'
-export type LogLevel = 'error' | 'warn' | 'info' | 'debug'
-
-export class Env {
-  @IsEnum(['development', 'test', 'production'])
-  NODE_ENV: NodeEnv
-
-  @IsInt()
-  @Min(1)
-  @Max(65535)
-  PORT: number
-
-  @IsString()
-  @MinLength(1)
-  DATABASE_URL: string
-
-  @IsString()
-  @MinLength(1)
-  AUTH_DATABASE_URL: string
-
-  @IsString()
-  @MinLength(32)
-  BETTER_AUTH_SECRET: string
-
-  @IsString()
-  @MinLength(1)
-  BETTER_AUTH_URL: string
-
-  @IsString()
-  @MinLength(1)
-  WEB_ORIGIN: string
-
-  @IsOptional()
-  @Matches(/^[a-z][a-z0-9+.-]*$/)
-  MOBILE_APP_SCHEME?: string
-
-  @IsEnum(['error', 'warn', 'info', 'debug'])
-  LOG_LEVEL: LogLevel
-}
-
-export function validate(raw: Record<string, unknown>): Env {
-  const env = plainToInstance(Env, raw, { enableImplicitConversion: true })
-  const errors = validateSync(env, { whitelist: true, forbidUnknownValues: false })
-
-  if (errors.length > 0) {
-    const named = errors.map((error) => error.property).join(', ')
-    throw new Error(`Invalid environment: ${named}`)
-  }
-
-  loaded = env
-  return env
-}
-
-let loaded: Env | undefined
-
-export function loadEnv(): Env {
-  if (loaded !== undefined) {
-    return loaded
-  }
-
-  if (process.env.NODE_ENV !== 'production' && existsSync('.env')) {
-    process.loadEnvFile('.env')
-  }
-
-  return validate(process.env)
-}

package/templates/api/src/errors/problem-details.filter.ts

@@ -1,86 +0,0 @@
-import {
-  type ArgumentsHost,
-  Catch,
-  type ExceptionFilter,
-  HttpException,
-  HttpStatus,
-  Logger,
-} from '@nestjs/common'
-import type { Request, Response } from 'express'
-import { RequestContextService } from '@/request-context/request-context.service'
-import { ValidationFailedException } from './validation-exception.factory'
-
-type ProblemDocument = {
-  type: string
-  title: string
-  status: number
-  detail: string
-  instance: string
-  requestId?: string
-  errors?: Record<string, string[]>
-}
-
-const TITLES: Record<number, string> = {
-  400: 'Bad Request',
-  401: 'Unauthorized',
-  403: 'Forbidden',
-  404: 'Not Found',
-  409: 'Conflict',
-  422: 'Unprocessable Entity',
-  500: 'Internal Server Error',
-  503: 'Service Unavailable',
-}
-
-function detailOf(exception: HttpException): string {
-  const response = exception.getResponse()
-
-  if (typeof response === 'string') {
-    return response
-  }
-
-  const message = (response as { message?: unknown }).message
-
-  if (typeof message === 'string') {
-    return message
-  }
-
-  return exception.message
-}
-
-@Catch()
-export class ProblemDetailsFilter implements ExceptionFilter {
-  private readonly logger = new Logger(ProblemDetailsFilter.name)
-
-  constructor(private readonly context: RequestContextService) {}
-
-  catch(exception: unknown, host: ArgumentsHost): void {
-    const http = host.switchToHttp()
-    const request = http.getRequest<Request>()
-    const response = http.getResponse<Response>()
-
-    const status =
-      exception instanceof HttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR
-
-    const problem: ProblemDocument = {
-      type: 'about:blank',
-      title: TITLES[status] ?? 'Error',
-      status,
-      detail:
-        exception instanceof HttpException && status < HttpStatus.INTERNAL_SERVER_ERROR
-          ? detailOf(exception)
-          : 'An unexpected error occurred.',
-      instance: request.originalUrl,
-      requestId: this.context.requestId,
-    }
-
-    if (exception instanceof ValidationFailedException) {
-      problem.errors = exception.fields
-    }
-
-    if (status >= HttpStatus.INTERNAL_SERVER_ERROR) {
-      this.logger.error(exception)
-    }
-
-    response.status(status).type('application/problem+json').json(problem)
-  }
-}

package/templates/api/src/errors/validation-exception.factory.ts

@@ -1,30 +0,0 @@
-import { BadRequestException, type ValidationError } from '@nestjs/common'
-
-export type FieldErrors = Record<string, string[]>
-
-function collect(errors: ValidationError[], prefix: string, into: FieldErrors): void {
-  for (const error of errors) {
-    const key = prefix === '' ? error.property : `${prefix}.${error.property}`
-    const messages = Object.values(error.constraints ?? {})
-
-    if (messages.length > 0) {
-      into[key] = messages
-    }
-
-    if (error.children !== undefined && error.children.length > 0) {
-      collect(error.children, key, into)
-    }
-  }
-}
-
-export class ValidationFailedException extends BadRequestException {
-  constructor(readonly fields: FieldErrors) {
-    super('Validation failed')
-  }
-}
-
-export function validationExceptionFactory(errors: ValidationError[]): ValidationFailedException {
-  const fields: FieldErrors = {}
-  collect(errors, '', fields)
-  return new ValidationFailedException(fields)
-}

package/templates/api/src/health/health.controller.ts

@@ -1,32 +0,0 @@
-import { Controller, Get, VERSION_NEUTRAL } from '@nestjs/common'
-import { ApiTags } from '@nestjs/swagger'
-import {
-  HealthCheck,
-  type HealthCheckResult,
-  HealthCheckService,
-  MikroOrmHealthIndicator,
-} from '@nestjs/terminus'
-import { Public } from '@/auth/public.decorator'
-
-@ApiTags('health')
-@Controller({ path: 'health', version: VERSION_NEUTRAL })
-export class HealthController {
-  constructor(
-    private readonly health: HealthCheckService,
-    private readonly database: MikroOrmHealthIndicator,
-  ) {}
-
-  @Public()
-  @Get('live')
-  @HealthCheck()
-  live(): Promise<HealthCheckResult> {
-    return this.health.check([])
-  }
-
-  @Public()
-  @Get('ready')
-  @HealthCheck()
-  ready(): Promise<HealthCheckResult> {
-    return this.health.check([() => this.database.pingCheck('database')])
-  }
-}

package/templates/api/src/health/health.module.ts

@@ -1,9 +0,0 @@
-import { Module } from '@nestjs/common'
-import { TerminusModule } from '@nestjs/terminus'
-import { HealthController } from './health.controller'
-
-@Module({
-  imports: [TerminusModule],
-  controllers: [HealthController],
-})
-export class HealthModule {}

package/templates/api/src/main.ts

@@ -1,43 +0,0 @@
-import { MikroORM } from '@mikro-orm/postgresql'
-import { ClassSerializerInterceptor, ValidationPipe, VersioningType } from '@nestjs/common'
-import { NestFactory, Reflector } from '@nestjs/core'
-import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger'
-import { Logger } from 'nestjs-pino'
-import { AppModule } from './app.module'
-import { Env } from './config/env'
-import { validationExceptionFactory } from './errors/validation-exception.factory'
-
-async function bootstrap(): Promise<void> {
-  const app = await NestFactory.create(AppModule, { bufferLogs: true })
-  const env = app.get(Env)
-
-  app.useLogger(app.get(Logger))
-  app.setGlobalPrefix('api')
-  app.enableCors({ origin: env.WEB_ORIGIN, credentials: true, exposedHeaders: ['X-Request-Id'] })
-  app.enableVersioning({ type: VersioningType.URI })
-
-  app.useGlobalPipes(
-    new ValidationPipe({
-      whitelist: true,
-      forbidNonWhitelisted: true,
-      transform: true,
-      exceptionFactory: validationExceptionFactory,
-    }),
-  )
-  app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)))
-
-  if (env.NODE_ENV !== 'production') {
-    const document = SwaggerModule.createDocument(
-      app,
-      new DocumentBuilder().setTitle('API').setVersion('1').build(),
-    )
-    SwaggerModule.setup('api/docs', app, document)
-  }
-
-  // MikroORM 7 no longer connects on init, so readiness would report the database down until a first query.
-  await app.get(MikroORM).connect()
-
-  await app.listen(env.PORT)
-}
-
-void bootstrap()

package/templates/api/src/mikro-orm.factory.ts

@@ -1,14 +0,0 @@
-import { Migrator } from '@mikro-orm/migrations'
-import { defineConfig } from '@mikro-orm/postgresql'
-import type { Env } from './config/env'
-import { Profile } from './users/entities/profile.entity'
-
-export function createOrmConfig(env: Pick<Env, 'DATABASE_URL' | 'NODE_ENV'>) {
-  return defineConfig({
-    clientUrl: env.DATABASE_URL,
-    entities: [Profile],
-    extensions: [Migrator],
-    migrations: { path: './migrations', snapshot: false },
-    debug: env.NODE_ENV === 'development',
-  })
-}

package/templates/api/src/request-context/request-context.module.ts

@@ -1,9 +0,0 @@
-import { Global, Module } from '@nestjs/common'
-import { RequestContextService } from './request-context.service'
-
-@Global()
-@Module({
-  providers: [RequestContextService],
-  exports: [RequestContextService],
-})
-export class RequestContextModule {}

package/templates/api/src/request-context/request-context.service.ts

@@ -1,17 +0,0 @@
-import { AsyncLocalStorage } from 'node:async_hooks'
-import { Injectable } from '@nestjs/common'
-
-type Store = { requestId: string }
-
-@Injectable()
-export class RequestContextService {
-  private readonly storage = new AsyncLocalStorage<Store>()
-
-  run<T>(requestId: string, callback: () => T): T {
-    return this.storage.run({ requestId }, callback)
-  }
-
-  get requestId(): string | undefined {
-    return this.storage.getStore()?.requestId
-  }
-}