speedrun-cli 2.6.1

package/templates/README.md

@@ -0,0 +1,81 @@
+# Templates Structure
+
+This directory contains modular templates for generating NestJS authentication projects.
+
+## Directory Structure
+
+```
+templates/
+├── base/                    # Shared, ORM-agnostic code (80% of the project)
+│   ├── src/
+│   │   ├── common/          # Guards, decorators, filters, interceptors
+│   │   ├── config/          # Configuration module, logger
+│   │   ├── modules/
+│   │   │   ├── auth/        # Auth controller & DTOs (no service - ORM-specific)
+│   │   │   └── users/       # Users controller & DTOs (no service - ORM-specific)
+│   │   └── main.ts          # Application entry point
+│   ├── test/                # E2E tests
+│   ├── tsconfig.json
+│   ├── tsconfig.build.json
+│   ├── nest-cli.json
+│   └── eslint.config.mjs
+│
+├── orm/                     # ORM-specific implementations
+│   ├── prisma/              # Prisma adapter
+│   │   ├── prisma/          # Schema & seed files
+│   │   ├── src/
+│   │   │   ├── prisma/      # PrismaService & PrismaModule
+│   │   │   ├── modules/
+│   │   │   │   ├── auth/    # Auth service & module
+│   │   │   │   ├── users/   # Users service & module
+│   │   │   │   └── health/  # Health controller (DB-aware)
+│   │   │   ├── config/      # env.validation.ts
+│   │   │   └── app.module.ts
+│   │   └── package.json     # ORM-specific dependencies
+│   │
+│   ├── typeorm/             # (Future) TypeORM adapter
+│   ├── mongoose/            # (Future) Mongoose adapter
+│   └── drizzle/             # (Future) Drizzle adapter
+│
+└── database/                # Database-specific configurations
+    ├── postgres/
+    │   ├── .env.example
+    │   └── prisma/schema.prisma  # (if different from default)
+    ├── mysql/
+    │   ├── .env.example
+    │   └── prisma/schema.prisma
+    ├── sqlite/
+    │   ├── .env.example
+    │   └── prisma/schema.prisma
+    └── mongodb/
+        ├── .env.example
+        └── prisma/schema.prisma
+```
+
+## How Generation Works
+
+1. **Copy base template** → All shared code (guards, decorators, main.ts, etc.)
+2. **Copy ORM adapter** → Overwrites/adds ORM-specific files (services, modules)
+3. **Copy database config** → Overwrites database-specific files (schema, .env)
+
+## Adding a New ORM
+
+1. Create `templates/orm/<orm-name>/` directory
+2. Add ORM-specific files:
+   - `src/<orm>/` - ORM service & module
+   - `src/modules/auth/auth.service.ts` - Auth service using the ORM
+   - `src/modules/auth/auth.module.ts` - Auth module with ORM imports
+   - `src/modules/users/users.service.ts` - Users service
+   - `src/modules/users/users.module.ts` - Users module
+   - `src/modules/health/` - Health check with DB indicator
+   - `src/app.module.ts` - Root module with ORM imports
+   - `package.json` - ORM-specific dependencies
+3. Update `index.js` to add the ORM to `ORM_OPTIONS`
+
+## Adding a New Database
+
+1. Create `templates/database/<db-name>/` directory
+2. Add database-specific files:
+   - `.env.example` - With correct DATABASE_URL format
+   - `prisma/schema.prisma` - (If using Prisma) DB-specific schema
+3. Update `index.js` to add the database to `DATABASE_OPTIONS`

package/templates/base/eslint.config.mjs

@@ -0,0 +1,34 @@
+// @ts-check
+import eslint from '@eslint/js';
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  {
+    ignores: ['eslint.config.mjs'],
+  },
+  eslint.configs.recommended,
+  ...tseslint.configs.recommendedTypeChecked,
+  eslintPluginPrettierRecommended,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.jest,
+      },
+      sourceType: 'commonjs',
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-floating-promises': 'warn',
+      '@typescript-eslint/no-unsafe-argument': 'warn'
+    },
+  },
+);

package/templates/base/gitignore

@@ -0,0 +1,78 @@
+# Dependencies
+node_modules/
+/.pnp
+.pnp.js
+
+# Build output
+/dist
+/build
+
+# Environment files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+*.env
+
+# Keep example env file
+!.env.example
+
+# Logs
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# OS files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*.sublime-workspace
+*.sublime-project
+
+# Testing
+/coverage
+/.nyc_output
+
+# Prisma
+prisma/*.db
+prisma/*.db-journal
+
+# SQLite
+*.db
+*.db-journal
+*.sqlite
+*.sqlite3
+
+# Drizzle
+drizzle/meta/
+
+# TypeORM
+/migrations/*.js
+/migrations/*.js.map
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+*.temp
+
+# Package manager lock files (optional - uncomment if you want to ignore)
+# package-lock.json
+# yarn.lock
+# pnpm-lock.yaml
+# bun.lockb

package/templates/base/nest-cli.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}

package/templates/base/src/common/constants/cookie.config.ts

@@ -0,0 +1,20 @@
+export const COOKIE_CONFIG = {
+  ACCESS_TOKEN: {
+    name: 'accessToken',
+    options: {
+      httpOnly: true,
+      sameSite: process.env.NODE_ENV === 'production' ? 'strict' : 'lax',
+      secure: process.env.NODE_ENV === 'production',
+      maxAge: 60 * 60 * 1000, // 1 hour
+    },
+  },
+  REFRESH_TOKEN: {
+    name: 'refreshToken',
+    options: {
+      httpOnly: true,
+      sameSite: process.env.NODE_ENV === 'production' ? 'strict' : 'lax',
+      secure: process.env.NODE_ENV === 'production',
+      maxAge: 30 * 24 * 60 * 60 * 1000, // 30 days
+    },
+  },
+} as const;

package/templates/base/src/common/decorators/get-user.decorator.ts

@@ -0,0 +1,13 @@
+import { createParamDecorator, ExecutionContext } from '@nestjs/common';
+
+interface RequestWithUser {
+  user?: Record<string, unknown>;
+}
+
+export const GetUser = createParamDecorator(
+  (data: string | undefined, ctx: ExecutionContext) => {
+    const request = ctx.switchToHttp().getRequest<RequestWithUser>();
+    const user = request.user;
+    return data && user ? user[data] : user;
+  },
+);

package/templates/base/src/common/decorators/public.decorator.ts

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

package/templates/base/src/common/decorators/roles.decorator.ts

@@ -0,0 +1,4 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const ROLES_KEY = 'roles';
+export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);

package/templates/base/src/common/dtos/pagination.dto.ts

@@ -0,0 +1,29 @@
+import { IsOptional, IsInt, Min, Max } from 'class-validator';
+import { Type } from 'class-transformer';
+
+export class PaginationDto {
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number = 1;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit?: number = 10;
+}
+
+export interface PaginatedResponse<T> {
+  data: T[];
+  meta: {
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrevious: boolean;
+  };
+}

package/templates/base/src/common/filters/http-exception.filter.ts

@@ -0,0 +1,108 @@
+import {
+  ExceptionFilter,
+  Catch,
+  ArgumentsHost,
+  HttpException,
+  HttpStatus,
+  Inject,
+} from '@nestjs/common';
+import { Request, Response } from 'express';
+import { ApiResponse } from '../interfaces/api-response.interface';
+import { Logger } from 'nestjs-pino';
+
+@Catch()
+export class HttpExceptionFilter implements ExceptionFilter {
+  constructor(@Inject(Logger) private readonly logger: Logger) {}
+
+  catch(exception: unknown, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const request = ctx.getRequest<Request>();
+    const response = ctx.getResponse<Response>();
+    const correlationId = request['correlationId'] as string;
+
+    let status = HttpStatus.INTERNAL_SERVER_ERROR;
+    let message = 'Internal server error';
+    let code = 'INTERNAL_SERVER_ERROR';
+    let details: unknown = undefined;
+
+    if (exception instanceof HttpException) {
+      status = exception.getStatus();
+      const exceptionResponse = exception.getResponse();
+
+      if (typeof exceptionResponse === 'string') {
+        message = exceptionResponse;
+      } else if (
+        typeof exceptionResponse === 'object' &&
+        exceptionResponse !== null
+      ) {
+        const responseObj = exceptionResponse as Record<string, unknown>;
+        message =
+          (typeof responseObj.message === 'string'
+            ? responseObj.message
+            : undefined) || message;
+        details = responseObj.error || responseObj.details;
+      }
+
+      // Generate error code from status
+      code = this.getErrorCode(status, message);
+    } else if (exception instanceof Error) {
+      message = exception.message;
+      code = 'INTERNAL_SERVER_ERROR';
+    }
+
+    // Log the error with correlation ID
+    this.logger.error(
+      {
+        correlationId,
+        statusCode: status,
+        errorCode: code,
+        message,
+        details,
+        path: request.url,
+        method: request.method,
+        stack: exception instanceof Error ? exception.stack : undefined,
+      },
+      `Error occurred: ${message}`,
+    );
+
+    const errorResponse: ApiResponse = {
+      success: false,
+      error: {
+        message,
+        code,
+        ...(details !== undefined && { details }),
+      },
+      meta: {
+        correlationId,
+      },
+    };
+
+    response.status(status).json(errorResponse);
+  }
+
+  private getErrorCode(status: number, message: string): string {
+    // Convert message to error code format
+    const messageCode = message
+      .toUpperCase()
+      .replace(/[^A-Z0-9]+/g, '_')
+      .replace(/^_|_$/g, '');
+
+    // Map common HTTP status codes
+    const statusCodeMap: { [key: number]: string } = {
+      400: 'BAD_REQUEST',
+      401: 'UNAUTHORIZED',
+      403: 'FORBIDDEN',
+      404: 'NOT_FOUND',
+      409: 'CONFLICT',
+      422: 'UNPROCESSABLE_ENTITY',
+      500: 'INTERNAL_SERVER_ERROR',
+    };
+
+    // If we have a specific message code, use it, otherwise use status code
+    if (messageCode && messageCode !== statusCodeMap[status]) {
+      return messageCode;
+    }
+
+    return statusCodeMap[status] || 'INTERNAL_SERVER_ERROR';
+  }
+}

package/templates/base/src/common/guards/auth.guard.ts

@@ -0,0 +1,51 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { Reflector } from '@nestjs/core';
+import { JwtService } from '@nestjs/jwt';
+import { COOKIE_CONFIG } from '../constants/cookie.config';
+
+@Injectable()
+export class AuthGuard implements CanActivate {
+  constructor(
+    private jwtService: JwtService,
+    private config: ConfigService,
+    private reflector: Reflector,
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const isPublic = this.reflector.getAllAndOverride<boolean>('isPublic', [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+
+    if (isPublic) {
+      return true;
+    }
+
+    const request = context.switchToHttp().getRequest<{
+      cookies: Record<string, string>;
+      user?: unknown;
+    }>();
+    const token = request.cookies[COOKIE_CONFIG.ACCESS_TOKEN.name];
+
+    if (!token || typeof token !== 'string') {
+      throw new UnauthorizedException('Access Token missing or malformed');
+    }
+
+    try {
+      const payload: unknown = await this.jwtService.verifyAsync(token, {
+        secret: this.config.get<string>('JWT_ACCESS_SECRET'),
+      });
+
+      request.user = payload;
+      return true;
+    } catch {
+      throw new UnauthorizedException('Invalid or expired Access Token');
+    }
+  }
+}

package/templates/base/src/common/guards/refresh-token.guard.ts

@@ -0,0 +1,39 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { JwtService } from '@nestjs/jwt';
+import { COOKIE_CONFIG } from '../constants/cookie.config';
+
+@Injectable()
+export class RefreshTokenGuard implements CanActivate {
+  constructor(
+    private jwtService: JwtService,
+    private config: ConfigService,
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = context.switchToHttp().getRequest<{
+      cookies: Record<string, string>;
+      user?: unknown;
+    }>();
+    const token = request.cookies[COOKIE_CONFIG.REFRESH_TOKEN.name];
+
+    if (!token || typeof token !== 'string') {
+      throw new UnauthorizedException('Refresh Token missing or malformed');
+    }
+
+    try {
+      const payload: unknown = await this.jwtService.verifyAsync(token, {
+        secret: this.config.get<string>('JWT_REFRESH_SECRET'),
+      });
+      request.user = payload;
+      return true;
+    } catch {
+      throw new UnauthorizedException('Invalid or expired Refresh Token');
+    }
+  }
+}

package/templates/base/src/common/guards/roles.guard.ts

@@ -0,0 +1,45 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  ForbiddenException,
+  Injectable,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { ROLES_KEY } from '../decorators/roles.decorator';
+
+// ORM-agnostic UserRole enum - define your own or import from your ORM
+export enum UserRole {
+  USER = 'USER',
+  ADMIN = 'ADMIN',
+}
+
+@Injectable()
+export class RolesGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const requiredRoles = this.reflector.getAllAndOverride<UserRole[]>(
+      ROLES_KEY,
+      [context.getHandler(), context.getClass()],
+    );
+
+    if (!requiredRoles) {
+      return true;
+    }
+
+    const request = context.switchToHttp().getRequest<{
+      user?: { role: UserRole };
+    }>();
+    const { user } = request;
+    if (!user) {
+      throw new UnauthorizedException('User not found in request');
+    }
+
+    if (!requiredRoles.includes(user.role)) {
+      throw new ForbiddenException('Insufficient role to access this resource');
+    }
+
+    return true;
+  }
+}

package/templates/base/src/common/interceptors/response.interceptor.ts

@@ -0,0 +1,55 @@
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+} from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+import { ApiResponse } from '../interfaces/api-response.interface';
+import { Request } from 'express';
+
+@Injectable()
+export class ResponseInterceptor<T>
+  implements NestInterceptor<T, ApiResponse<T>>
+{
+  intercept(
+    context: ExecutionContext,
+    next: CallHandler,
+  ): Observable<ApiResponse<T>> {
+    const request = context.switchToHttp().getRequest<Request>();
+    const correlationId = request['correlationId'] as string;
+
+    return next.handle().pipe(
+      map((data: T | ApiResponse<T>) => {
+        // If the response is already in the correct format, return it
+        if (
+          data &&
+          typeof data === 'object' &&
+          'success' in data &&
+          'meta' in data
+        ) {
+          const existingMeta = data.meta || {};
+          return {
+            ...data,
+            meta: {
+              ...existingMeta,
+              correlationId,
+              timestamp: new Date().toISOString(),
+            },
+          } as ApiResponse<T>;
+        }
+
+        // Otherwise, wrap it in the standard format
+        return {
+          success: true,
+          data: data as T | undefined,
+          meta: {
+            correlationId,
+            timestamp: new Date().toISOString(),
+          },
+        } as ApiResponse<T>;
+      }),
+    );
+  }
+}

package/templates/base/src/common/interfaces/api-response.interface.ts

@@ -0,0 +1,26 @@
+export interface ApiResponse<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: ApiError;
+  meta?: ApiMeta;
+}
+
+export interface ApiError {
+  message: string;
+  code: string;
+  details?: unknown;
+}
+
+export interface ApiMeta {
+  timestamp?: string;
+  requestId?: string;
+  pagination?: PaginationMeta;
+  [key: string]: unknown;
+}
+
+export interface PaginationMeta {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+}

package/templates/base/src/common/middleware/correlation-id.middleware.ts

@@ -0,0 +1,20 @@
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { Request, Response, NextFunction } from 'express';
+import { randomUUID } from 'crypto';
+
+@Injectable()
+export class CorrelationIdMiddleware implements NestMiddleware {
+  use(req: Request, res: Response, next: NextFunction) {
+    // Get correlation ID from header or generate new one
+    const correlationId =
+      (req.headers['x-correlation-id'] as string) || randomUUID();
+
+    // Attach to request for later use
+    req['correlationId'] = correlationId;
+
+    // Set response header
+    res.setHeader('X-Correlation-ID', correlationId);
+
+    next();
+  }
+}

package/templates/base/src/common/validators/password.validator.ts

@@ -0,0 +1,37 @@
+import { registerDecorator, ValidationOptions } from 'class-validator';
+
+export function IsStrongPassword(validationOptions?: ValidationOptions) {
+  return function (object: object, propertyName: string) {
+    registerDecorator({
+      name: 'isStrongPassword',
+      target: object.constructor,
+      propertyName: propertyName,
+      options: validationOptions,
+      validator: {
+        validate(value: unknown) {
+          if (typeof value !== 'string') return false;
+
+          // At least 8 characters
+          if (value.length < 8) return false;
+
+          // At least one uppercase letter
+          if (!/[A-Z]/.test(value)) return false;
+
+          // At least one lowercase letter
+          if (!/[a-z]/.test(value)) return false;
+
+          // At least one number
+          if (!/[0-9]/.test(value)) return false;
+
+          // At least one special character
+          if (!/[!@#$%^&*()_+\-=[\]{};':"\\|,.<>/?]/.test(value)) return false;
+
+          return true;
+        },
+        defaultMessage() {
+          return 'Password must contain at least 8 characters, including one uppercase letter, one lowercase letter, one number, and one special character';
+        },
+      },
+    });
+  };
+}

package/templates/base/src/config/config.module.ts

@@ -0,0 +1,14 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { validate } from './env.validation';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      isGlobal: true,
+      envFilePath: '.env',
+      validate,
+    }),
+  ],
+})
+export class AppConfigModule {}