create-nara 1.0.23 → 1.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nara",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "description": "CLI to scaffold NARA projects",
   "type": "module",
   "bin": {

package/templates/base/app/config/constants.ts

@@ -0,0 +1,251 @@
+/**
+ * Application Constants
+ *
+ * Centralized configuration values to avoid magic numbers/strings
+ * scattered throughout the codebase.
+ */
+
+// ============================================
+// Server Configuration
+// ============================================
+
+export const SERVER = {
+  /** Maximum request body size in bytes (10MB) */
+  MAX_BODY_SIZE: 10 * 1024 * 1024,
+
+  /** Default server port */
+  DEFAULT_PORT: 3000,
+
+  /** Default Vite dev server port */
+  DEFAULT_VITE_PORT: 5173,
+} as const;
+
+// ============================================
+// Authentication & Security
+// ============================================
+
+export const AUTH = {
+  /** JWT expiry in seconds (7 days) */
+  JWT_EXPIRY_SECONDS: 7 * 24 * 60 * 60,
+
+  /** Session cookie expiry in milliseconds (30 days) */
+  SESSION_EXPIRY_MS: 30 * 24 * 60 * 60 * 1000,
+
+  /** Error cookie expiry in milliseconds (5 minutes) */
+  ERROR_COOKIE_EXPIRY_MS: 5 * 60 * 1000,
+
+  /** Minimum password length */
+  MIN_PASSWORD_LENGTH: 8,
+
+  /** Maximum password length */
+  MAX_PASSWORD_LENGTH: 100,
+
+  /** Bcrypt salt rounds */
+  BCRYPT_SALT_ROUNDS: 10,
+} as const;
+
+// ============================================
+// Pagination
+// ============================================
+
+export const PAGINATION = {
+  /** Default page size */
+  DEFAULT_PAGE_SIZE: 10,
+
+  /** Maximum page size allowed */
+  MAX_PAGE_SIZE: 100,
+
+  /** Default page number */
+  DEFAULT_PAGE: 1,
+} as const;
+
+// ============================================
+// User & Profile
+// ============================================
+
+export const USER = {
+  /** Minimum name length */
+  MIN_NAME_LENGTH: 2,
+
+  /** Maximum name length */
+  MAX_NAME_LENGTH: 100,
+
+  /** Minimum phone length */
+  MIN_PHONE_LENGTH: 10,
+
+  /** Maximum phone length */
+  MAX_PHONE_LENGTH: 20,
+} as const;
+
+// ============================================
+// File Upload
+// ============================================
+
+export const UPLOAD = {
+  /** Maximum file size in bytes (5MB) */
+  MAX_FILE_SIZE: 5 * 1024 * 1024,
+
+  /** Allowed image extensions */
+  ALLOWED_IMAGE_EXTENSIONS: ['jpg', 'jpeg', 'png', 'gif', 'webp', 'svg'],
+
+  /** Allowed document extensions */
+  ALLOWED_DOC_EXTENSIONS: ['pdf', 'doc', 'docx', 'xls', 'xlsx'],
+
+  /** Avatar upload directory */
+  AVATAR_DIR: 'avatars',
+
+  /** General assets directory */
+  ASSETS_DIR: 'assets',
+} as const;
+
+// ============================================
+// Cache & Performance
+// ============================================
+
+export const CACHE = {
+  /** Static asset cache duration in seconds (1 year) */
+  STATIC_ASSET_MAX_AGE: 365 * 24 * 60 * 60,
+
+  /** API response cache duration in seconds (5 minutes) */
+  API_CACHE_DURATION: 5 * 60,
+
+  /** Session cache duration in seconds (1 hour) */
+  SESSION_CACHE_DURATION: 60 * 60,
+} as const;
+
+// ============================================
+// Rate Limiting
+// ============================================
+
+export const RATE_LIMIT = {
+  /** Maximum requests per window (general) */
+  MAX_REQUESTS: 100,
+
+  /** Window duration in milliseconds (15 minutes) */
+  WINDOW_MS: 15 * 60 * 1000,
+
+  /** Login attempts before lockout */
+  MAX_LOGIN_ATTEMPTS: 5,
+
+  /** Login lockout duration in milliseconds (15 minutes) */
+  LOGIN_LOCKOUT_MS: 15 * 60 * 1000,
+
+  /** API rate limit (requests per minute) */
+  API_MAX_REQUESTS: 60,
+
+  /** API rate limit window (1 minute) */
+  API_WINDOW_MS: 60 * 1000,
+
+  /** Strict rate limit for sensitive endpoints */
+  STRICT_MAX_REQUESTS: 10,
+
+  /** Strict rate limit window (1 minute) */
+  STRICT_WINDOW_MS: 60 * 1000,
+} as const;
+
+// ============================================
+// Security Headers
+// ============================================
+
+export const SECURITY = {
+  /** HSTS max-age in seconds (1 year) */
+  HSTS_MAX_AGE: 365 * 24 * 60 * 60,
+
+  /** CSRF token length in bytes */
+  CSRF_TOKEN_LENGTH: 32,
+
+  /** CSRF cookie max age in seconds (24 hours) */
+  CSRF_COOKIE_MAX_AGE: 24 * 60 * 60,
+
+  /** CSRF cookie name */
+  CSRF_COOKIE_NAME: 'csrf_token',
+
+  /** CSRF header name */
+  CSRF_HEADER_NAME: 'X-CSRF-Token',
+} as const;
+
+// ============================================
+// Database
+// ============================================
+
+export const DATABASE = {
+  /** Default connection type */
+  DEFAULT_CONNECTION: 'development',
+
+  /** Connection pool min */
+  POOL_MIN: 2,
+
+  /** Connection pool max */
+  POOL_MAX: 10,
+} as const;
+
+// ============================================
+// Logging
+// ============================================
+
+export const LOGGING = {
+  /** Available log levels */
+  LEVELS: ['trace', 'debug', 'info', 'warn', 'error', 'fatal'] as const,
+
+  /** Default log level */
+  DEFAULT_LEVEL: 'info',
+
+  /** Log file directory */
+  LOG_DIR: 'logs',
+
+  /** Max log file size in bytes (10MB) */
+  MAX_LOG_SIZE: 10 * 1024 * 1024,
+
+  /** Number of log files to keep */
+  MAX_LOG_FILES: 10,
+} as const;
+
+// ============================================
+// HTTP Status Codes (commonly used)
+// ============================================
+
+export const HTTP_STATUS = {
+  OK: 200,
+  CREATED: 201,
+  NO_CONTENT: 204,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  UNPROCESSABLE_ENTITY: 422,
+  TOO_MANY_REQUESTS: 429,
+  INTERNAL_SERVER_ERROR: 500,
+  SERVICE_UNAVAILABLE: 503,
+} as const;
+
+// ============================================
+// Error Messages
+// ============================================
+
+export const ERROR_MESSAGES = {
+  UNAUTHORIZED: 'Unauthorized',
+  FORBIDDEN: 'Access denied',
+  NOT_FOUND: 'Not found',
+  VALIDATION_FAILED: 'Validation failed',
+  INTERNAL_ERROR: 'Internal server error',
+  INVALID_CREDENTIALS: 'Invalid email or password',
+  EMAIL_EXISTS: 'Email already in use',
+  TOKEN_EXPIRED: 'Invalid or expired token',
+  SESSION_EXPIRED: 'Session expired, please login again',
+} as const;
+
+// ============================================
+// Success Messages
+// ============================================
+
+export const SUCCESS_MESSAGES = {
+  USER_CREATED: 'User created successfully',
+  USER_UPDATED: 'User updated successfully',
+  USER_DELETED: 'User deleted successfully',
+  PROFILE_UPDATED: 'Profile updated successfully',
+  PASSWORD_CHANGED: 'Password changed successfully',
+  PASSWORD_RESET_SENT: 'Password reset link sent',
+  LOGIN_SUCCESS: 'Login successful',
+  LOGOUT_SUCCESS: 'Logout successful',
+} as const;

package/templates/base/app/config/env.ts

@@ -0,0 +1,110 @@
+/**
+ * Environment Configuration & Validation
+ *
+ * Validates required environment variables on application startup.
+ * Provides typed access to environment configuration.
+ */
+import { SERVER, LOGGING } from './constants.js';
+
+// ============================================
+// Type Definitions
+// ============================================
+
+export interface Env {
+  // Server
+  NODE_ENV: 'development' | 'production' | 'test';
+  PORT: number;
+  APP_URL: string;
+
+  // Database
+  DB_CONNECTION: string;
+
+  // Auth
+  JWT_SECRET: string;
+
+  // Logging
+  LOG_LEVEL: typeof LOGGING.LEVELS[number];
+}
+
+// ============================================
+// Validation Function
+// ============================================
+
+/**
+ * Validate environment variables
+ * @returns Validated and typed environment object
+ * @throws Error if validation fails
+ */
+export function validateEnv(): Env {
+  const errors: string[] = [];
+  const env = process.env;
+
+  // Validate NODE_ENV
+  const validNodeEnvs = ['development', 'production', 'test'] as const;
+  const nodeEnv = env.NODE_ENV || 'development';
+  if (!validNodeEnvs.includes(nodeEnv as any)) {
+    errors.push(`  - NODE_ENV: Must be one of ${validNodeEnvs.join(', ')}`);
+  }
+
+  // Validate PORT
+  const port = parseInt(env.PORT || String(SERVER.DEFAULT_PORT), 10);
+  if (isNaN(port) || port <= 0) {
+    errors.push('  - PORT: Must be a positive number');
+  }
+
+  // Validate LOG_LEVEL
+  const logLevel = env.LOG_LEVEL || 'info';
+  if (!LOGGING.LEVELS.includes(logLevel as any)) {
+    errors.push(`  - LOG_LEVEL: Must be one of ${LOGGING.LEVELS.join(', ')}`);
+  }
+
+  // Warning for missing JWT_SECRET in production
+  if (nodeEnv === 'production' && !env.JWT_SECRET) {
+    errors.push('  - JWT_SECRET: Required in production');
+  }
+
+  if (errors.length > 0) {
+    console.error('\n❌ Environment validation failed:\n');
+    console.error(errors.join('\n'));
+    console.error('\nPlease check your .env file and ensure all required variables are set.\n');
+    process.exit(1);
+  }
+
+  return {
+    NODE_ENV: nodeEnv as 'development' | 'production' | 'test',
+    PORT: port,
+    APP_URL: env.APP_URL || `http://localhost:${port}`,
+    DB_CONNECTION: env.DB_CONNECTION || 'development',
+    JWT_SECRET: env.JWT_SECRET || 'your-secret-key',
+    LOG_LEVEL: logLevel as typeof LOGGING.LEVELS[number],
+  };
+}
+
+/**
+ * Get environment summary for logging
+ */
+export function getEnvSummary(env: Env) {
+  return {
+    nodeEnv: env.NODE_ENV,
+    port: env.PORT,
+    appUrl: env.APP_URL,
+    dbConnection: env.DB_CONNECTION,
+    logLevel: env.LOG_LEVEL,
+  };
+}
+
+// ============================================
+// Singleton Instance
+// ============================================
+
+let _env: Env | null = null;
+
+/**
+ * Get validated environment (lazy initialization)
+ */
+export function getEnv(): Env {
+  if (!_env) {
+    _env = validateEnv();
+  }
+  return _env;
+}

package/templates/base/app/config/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Config Module
+ *
+ * Re-exports all configuration modules.
+ */
+
+export * from './constants.js';
+export * from './env.js';

package/templates/base/app/services/Logger.ts

@@ -0,0 +1,161 @@
+/**
+ * Logger Service
+ *
+ * Simple structured logging without external dependencies.
+ * Supports multiple log levels and structured data.
+ */
+
+type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  trace: 10,
+  debug: 20,
+  info: 30,
+  warn: 40,
+  error: 50,
+  fatal: 60,
+};
+
+/**
+ * Get current log level from environment
+ */
+function getLogLevel(): LogLevel {
+  const level = (process.env.LOG_LEVEL || 'info').toLowerCase() as LogLevel;
+  return LOG_LEVELS[level] !== undefined ? level : 'info';
+}
+
+/**
+ * Check if a log level should be logged
+ */
+function shouldLog(level: LogLevel): boolean {
+  const currentLevel = getLogLevel();
+  return LOG_LEVELS[level] >= LOG_LEVELS[currentLevel];
+}
+
+/**
+ * Format log message with timestamp and metadata
+ */
+function formatLog(level: LogLevel, message: string, data?: Record<string, any>): string {
+  const timestamp = new Date().toISOString();
+  const levelUpper = level.toUpperCase().padEnd(5);
+
+  if (data && Object.keys(data).length > 0) {
+    return `[${timestamp}] ${levelUpper} ${message} ${JSON.stringify(data)}`;
+  }
+  return `[${timestamp}] ${levelUpper} ${message}`;
+}
+
+/**
+ * Logger class with utility methods
+ */
+class Logger {
+  /**
+   * Log trace level message (very detailed debugging)
+   */
+  trace(message: string, data?: Record<string, any>): void {
+    if (shouldLog('trace')) {
+      console.log(formatLog('trace', message, data));
+    }
+  }
+
+  /**
+   * Log debug level message
+   */
+  debug(message: string, data?: Record<string, any>): void {
+    if (shouldLog('debug')) {
+      console.log(formatLog('debug', message, data));
+    }
+  }
+
+  /**
+   * Log info level message
+   */
+  info(message: string, data?: Record<string, any>): void {
+    if (shouldLog('info')) {
+      console.log(formatLog('info', message, data));
+    }
+  }
+
+  /**
+   * Log warning level message
+   */
+  warn(message: string, data?: Record<string, any>): void {
+    if (shouldLog('warn')) {
+      console.warn(formatLog('warn', message, data));
+    }
+  }
+
+  /**
+   * Log error level message
+   */
+  error(message: string, error?: Error | Record<string, any>): void {
+    if (shouldLog('error')) {
+      if (error instanceof Error) {
+        console.error(formatLog('error', message, {
+          error: error.message,
+          stack: error.stack,
+        }));
+      } else if (error) {
+        console.error(formatLog('error', message, error));
+      } else {
+        console.error(formatLog('error', message));
+      }
+    }
+  }
+
+  /**
+   * Log fatal level message (application crash)
+   */
+  fatal(message: string, error?: Error | Record<string, any>): void {
+    if (shouldLog('fatal')) {
+      if (error instanceof Error) {
+        console.error(formatLog('fatal', message, {
+          error: error.message,
+          stack: error.stack,
+        }));
+      } else if (error) {
+        console.error(formatLog('fatal', message, error));
+      } else {
+        console.error(formatLog('fatal', message));
+      }
+    }
+  }
+
+  /**
+   * Log HTTP request
+   */
+  logRequest(data: {
+    method: string;
+    url: string;
+    statusCode?: number;
+    responseTime?: number;
+    userId?: string;
+    ip?: string;
+  }): void {
+    this.info('HTTP Request', data);
+  }
+
+  /**
+   * Log database query (use sparingly in production)
+   */
+  logQuery(query: string, duration?: number): void {
+    this.debug('Database Query', { query, duration });
+  }
+
+  /**
+   * Log authentication event
+   */
+  logAuth(event: string, data: Record<string, any>): void {
+    this.info(`Auth: ${event}`, data);
+  }
+
+  /**
+   * Log security event
+   */
+  logSecurity(event: string, data: Record<string, any>): void {
+    this.warn(`Security: ${event}`, data);
+  }
+}
+
+// Export singleton instance
+export default new Logger();