create-stackr 0.2.0

package/templates/base/backend/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "ES2022"
+    ],
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "allowJs": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "incremental": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": false,
+    "paths": {
+      "@/*": [
+        "./*"
+      ],
+      "@/domain/*": [
+        "./domain/*"
+      ]
+    }
+  },
+  "include": [
+    "**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}

package/templates/base/backend/utils/db.drizzle.ts

@@ -0,0 +1,41 @@
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { Pool } from 'pg';
+import * as schema from '../drizzle/schema';
+
+// Create connection pool
+const pool = new Pool({
+  connectionString: process.env.DATABASE_URL!,
+  max: 20,
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000,
+});
+
+// Create drizzle instance with schema
+export const db = drizzle(pool, { schema });
+
+// Export schema for type inference
+export { schema };
+
+// Test connection on startup
+pool.connect()
+  .then((client) => {
+    console.log('Database connected successfully');
+    client.release();
+  })
+  .catch((err) => {
+    console.error('Database connection failed:', err);
+    process.exit(1);
+  });
+
+// Gracefully close pool on process termination
+process.on('SIGINT', async () => {
+  await pool.end();
+  console.log('Database connection pool closed.');
+  process.exit(0);
+});
+
+process.on('SIGTERM', async () => {
+  await pool.end();
+  console.log('Database connection pool closed.');
+  process.exit(0);
+});

package/templates/base/backend/utils/db.prisma.ts

@@ -0,0 +1,51 @@
+import { PrismaClient } from "../prisma/generated/prisma/client";
+import { PrismaPg } from "@prisma/adapter-pg";
+
+let db: PrismaClient;
+
+declare global {
+  var __db: PrismaClient | undefined;
+}
+
+// Create adapter with connection string
+const createAdapter = () =>
+  new PrismaPg({
+    connectionString: process.env.DATABASE_URL,
+  });
+
+// Use global instance in development to prevent exhausting database connections during hot reloads
+if (process.env.NODE_ENV === "production") {
+  db = new PrismaClient({
+    adapter: createAdapter(),
+  });
+} else {
+  if (!global.__db) {
+    global.__db = new PrismaClient({
+      adapter: createAdapter(),
+    });
+  }
+  db = global.__db;
+}
+
+// Connect to database
+db.$connect()
+  .then(() => console.log("✅ Database connected successfully"))
+  .catch((err: any) => {
+    console.error("❌ Database connection failed:", err);
+    process.exit(1);
+  });
+
+// Gracefully disconnect on process termination
+process.on("SIGINT", async () => {
+  await db.$disconnect();
+  console.log("Database connection closed.");
+  process.exit(0);
+});
+
+process.on("SIGTERM", async () => {
+  await db.$disconnect();
+  console.log("Database connection closed.");
+  process.exit(0);
+});
+
+export { db };

package/templates/base/backend/utils/email.ts.ejs

@@ -0,0 +1,35 @@
+<% if (features.authentication.emailVerification || features.authentication.passwordReset) { %>
+import nodemailer from "nodemailer";
+
+const transporter = nodemailer.createTransport({
+  host: process.env.SMTP_HOST,
+  port: parseInt(process.env.SMTP_PORT || "587"),
+  secure: process.env.SMTP_PORT === "465",
+  auth: {
+    user: process.env.SMTP_USER,
+    pass: process.env.SMTP_PASS,
+  },
+});
+
+interface SendEmailOptions {
+  to: string;
+  subject: string;
+  html: string;
+  text?: string;
+}
+
+export async function sendEmail({ to, subject, html, text }: SendEmailOptions): Promise<void> {
+  await transporter.sendMail({
+    from: process.env.EMAIL_FROM || "noreply@example.com",
+    to,
+    subject,
+    html,
+    text: text || html.replace(/<[^>]*>/g, ""),
+  });
+}
+<% } else { %>
+// Email service not enabled - emailVerification and passwordReset are disabled
+export async function sendEmail(): Promise<void> {
+  throw new Error("Email service not configured");
+}
+<% } %>

package/templates/base/backend/utils/errors.ts

@@ -0,0 +1,348 @@
+import { FastifyError } from 'fastify';
+
+// Error codes enum for consistent error identification
+export enum ErrorCode {
+  // Authentication & Authorization
+  AUTH_UNAUTHORIZED = 'AUTH_UNAUTHORIZED',
+  AUTH_TOKEN_MISSING = 'AUTH_TOKEN_MISSING',
+  AUTH_TOKEN_INVALID = 'AUTH_TOKEN_INVALID',
+  AUTH_TOKEN_EXPIRED = 'AUTH_TOKEN_EXPIRED',
+  AUTH_USER_NOT_FOUND = 'AUTH_USER_NOT_FOUND',
+  AUTH_INVALID_CREDENTIALS = 'AUTH_INVALID_CREDENTIALS',
+  AUTH_PERMISSION_DENIED = 'AUTH_PERMISSION_DENIED',
+
+  // Session Management
+  SESSION_NOT_FOUND = 'SESSION_NOT_FOUND',
+  SESSION_EXPIRED = 'SESSION_EXPIRED',
+  SESSION_INVALID = 'SESSION_INVALID',
+  SESSION_MIGRATION_FAILED = 'SESSION_MIGRATION_FAILED',
+
+  // Validation
+  VALIDATION_FAILED = 'VALIDATION_FAILED',
+  VALIDATION_MISSING_FIELD = 'VALIDATION_MISSING_FIELD',
+  VALIDATION_INVALID_FORMAT = 'VALIDATION_INVALID_FORMAT',
+
+  // Business Logic
+  USER_ALREADY_EXISTS = 'USER_ALREADY_EXISTS',
+  USERNAME_ALREADY_EXISTS = 'USERNAME_ALREADY_EXISTS',
+  EMAIL_ALREADY_EXISTS = 'EMAIL_ALREADY_EXISTS',
+
+  // System Errors
+  DATABASE_ERROR = 'DATABASE_ERROR',
+  EXTERNAL_SERVICE_ERROR = 'EXTERNAL_SERVICE_ERROR',
+  INTERNAL_SERVER_ERROR = 'INTERNAL_SERVER_ERROR',
+
+  // Network & Connection
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  TIMEOUT_ERROR = 'TIMEOUT_ERROR',
+
+  // Resource Not Found
+  RESOURCE_NOT_FOUND = 'RESOURCE_NOT_FOUND',
+  ROUTE_NOT_FOUND = 'ROUTE_NOT_FOUND',
+
+  // Client Errors
+  CLIENT_ERROR = 'CLIENT_ERROR',
+}
+
+// Error severity levels
+export enum ErrorSeverity {
+  LOW = 'low',
+  MEDIUM = 'medium',
+  HIGH = 'high',
+  CRITICAL = 'critical',
+}
+
+// Standardized error response interface
+export interface ApiErrorResponse {
+  error: {
+    code: ErrorCode;
+    message: string;
+    details?: any;
+    timestamp: string;
+    requestId?: string;
+    path?: string;
+  };
+}
+
+// Custom application error class
+export class AppError extends Error {
+  public readonly code: ErrorCode;
+  public readonly statusCode: number;
+  public readonly severity: ErrorSeverity;
+  public readonly details?: any;
+  public readonly isOperational: boolean;
+
+  constructor(
+    code: ErrorCode,
+    message: string,
+    statusCode: number = 500,
+    severity: ErrorSeverity = ErrorSeverity.MEDIUM,
+    details?: any,
+    isOperational: boolean = true
+  ) {
+    super(message);
+    
+    this.code = code;
+    this.statusCode = statusCode;
+    this.severity = severity;
+    this.details = details;
+    this.isOperational = isOperational;
+
+    // Maintains proper stack trace for where our error was thrown
+    Error.captureStackTrace(this, this.constructor);
+  }
+
+  // Convert to API response format
+  toApiResponse(requestId?: string, path?: string): ApiErrorResponse {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        details: this.details,
+        timestamp: new Date().toISOString(),
+        requestId,
+        path,
+      },
+    };
+  }
+}
+
+// Factory functions for common errors
+export class ErrorFactory {
+  // Authentication errors
+  static unauthorized(message: string = 'Authentication required'): AppError {
+    return new AppError(
+      ErrorCode.AUTH_UNAUTHORIZED,
+      message,
+      401,
+      ErrorSeverity.MEDIUM
+    );
+  }
+
+  static tokenMissing(): AppError {
+    return new AppError(
+      ErrorCode.AUTH_TOKEN_MISSING,
+      'Authentication token is required',
+      401,
+      ErrorSeverity.MEDIUM
+    );
+  }
+
+  static tokenInvalid(details?: any): AppError {
+    return new AppError(
+      ErrorCode.AUTH_TOKEN_INVALID,
+      'Authentication token is invalid',
+      401,
+      ErrorSeverity.MEDIUM,
+      details
+    );
+  }
+
+  static tokenExpired(): AppError {
+    return new AppError(
+      ErrorCode.AUTH_TOKEN_EXPIRED,
+      'Authentication token has expired',
+      401,
+      ErrorSeverity.MEDIUM
+    );
+  }
+
+  static userNotFound(): AppError {
+    return new AppError(
+      ErrorCode.AUTH_USER_NOT_FOUND,
+      'User not found or no longer active',
+      401,
+      ErrorSeverity.MEDIUM
+    );
+  }
+
+  static invalidCredentials(): AppError {
+    return new AppError(
+      ErrorCode.AUTH_INVALID_CREDENTIALS,
+      'Invalid email or password',
+      401,
+      ErrorSeverity.MEDIUM
+    );
+  }
+
+  static permissionDenied(): AppError {
+    return new AppError(
+      ErrorCode.AUTH_PERMISSION_DENIED,
+      'You do not have permission to access this resource',
+      403,
+      ErrorSeverity.MEDIUM
+    );
+  }
+
+  // Session errors
+  static sessionNotFound(): AppError {
+    return new AppError(
+      ErrorCode.SESSION_NOT_FOUND,
+      'Session not found or expired',
+      401,
+      ErrorSeverity.MEDIUM
+    );
+  }
+
+  static sessionExpired(): AppError {
+    return new AppError(
+      ErrorCode.SESSION_EXPIRED,
+      'Session has expired',
+      401,
+      ErrorSeverity.MEDIUM
+    );
+  }
+
+  static sessionInvalid(details?: any): AppError {
+    return new AppError(
+      ErrorCode.SESSION_INVALID,
+      'Session is invalid',
+      401,
+      ErrorSeverity.MEDIUM,
+      details
+    );
+  }
+
+  static sessionMigrationFailed(details?: any): AppError {
+    return new AppError(
+      ErrorCode.SESSION_MIGRATION_FAILED,
+      'Failed to migrate session to user account',
+      500,
+      ErrorSeverity.HIGH,
+      details
+    );
+  }
+
+  // Validation errors
+  static validationFailed(details: any): AppError {
+    return new AppError(
+      ErrorCode.VALIDATION_FAILED,
+      'Request validation failed',
+      400,
+      ErrorSeverity.LOW,
+      details
+    );
+  }
+
+  static validationError(message: string): AppError {
+    return new AppError(
+      ErrorCode.VALIDATION_FAILED,
+      message,
+      400,
+      ErrorSeverity.LOW
+    );
+  }
+
+  // Business logic errors
+  static userAlreadyExists(): AppError {
+    return new AppError(
+      ErrorCode.USER_ALREADY_EXISTS,
+      'A user with this email already exists',
+      409,
+      ErrorSeverity.LOW
+    );
+  }
+
+  static usernameAlreadyExists(): AppError {
+    return new AppError(
+      ErrorCode.USERNAME_ALREADY_EXISTS,
+      'This username is already taken',
+      409,
+      ErrorSeverity.LOW
+    );
+  }
+
+  // System errors
+  static databaseError(details?: any): AppError {
+    return new AppError(
+      ErrorCode.DATABASE_ERROR,
+      'A database error occurred',
+      500,
+      ErrorSeverity.HIGH,
+      details,
+      false // Not operational - system issue
+    );
+  }
+
+  static internalServerError(details?: any): AppError {
+    return new AppError(
+      ErrorCode.INTERNAL_SERVER_ERROR,
+      'An internal server error occurred',
+      500,
+      ErrorSeverity.CRITICAL,
+      details,
+      false
+    );
+  }
+
+  static externalServiceError(service: string, details?: any): AppError {
+    return new AppError(
+      ErrorCode.EXTERNAL_SERVICE_ERROR,
+      `External service (${service}) is unavailable`,
+      503,
+      ErrorSeverity.HIGH,
+      details
+    );
+  }
+
+  // Resource errors
+  static resourceNotFound(resource: string = 'resource'): AppError {
+    return new AppError(
+      ErrorCode.RESOURCE_NOT_FOUND,
+      `The requested ${resource} was not found`,
+      404,
+      ErrorSeverity.LOW
+    );
+  }
+
+  static routeNotFound(method: string, path: string): AppError {
+    return new AppError(
+      ErrorCode.ROUTE_NOT_FOUND,
+      `Route ${method} ${path} not found`,
+      404,
+      ErrorSeverity.LOW,
+      { method, path }
+    );
+  }
+
+  static clientError(message: string = 'Bad request', statusCode: number = 400): AppError {
+    return new AppError(
+      ErrorCode.CLIENT_ERROR,
+      message,
+      statusCode,
+      ErrorSeverity.LOW
+    );
+  }
+}
+
+// Helper function to determine if an error should include details in the response
+export function shouldIncludeErrorDetails(error: AppError, isDevelopment: boolean): boolean {
+  // Always include details for operational errors in development
+  if (isDevelopment && error.isOperational) return true;
+  
+  // Never include details for non-operational (system) errors in production
+  if (!isDevelopment && !error.isOperational) return false;
+  
+  // Include details for low/medium severity operational errors
+  return error.isOperational && [ErrorSeverity.LOW, ErrorSeverity.MEDIUM].includes(error.severity);
+}
+
+// Helper to convert unknown errors to AppError
+export function normalizeError(error: unknown): AppError {
+  if (error instanceof AppError) {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    return new AppError(
+      ErrorCode.INTERNAL_SERVER_ERROR,
+      error.message,
+      500,
+      ErrorSeverity.CRITICAL,
+      { originalError: error.message },
+      false
+    );
+  }
+
+  return ErrorFactory.internalServerError({ originalError: String(error) });
+}