@zintrust/core 0.1.0

package/src/templates/project/basic/config/cache.ts.tpl

@@ -0,0 +1,117 @@
+/**
+ * Cache Configuration
+ * Caching drivers and settings
+ * Sealed namespace for immutability
+ */
+
+import { Env } from '@config/env';
+
+type MemoryCacheDriverConfig = {
+  driver: 'memory';
+  ttl: number;
+};
+
+type RedisCacheDriverConfig = {
+  driver: 'redis';
+  host: string;
+  port: number;
+  password: string | undefined;
+  database: number;
+  ttl: number;
+};
+
+type MemcachedCacheDriverConfig = {
+  driver: 'memcached';
+  servers: string[];
+  ttl: number;
+};
+
+type FileCacheDriverConfig = {
+  driver: 'file';
+  path: string;
+  ttl: number;
+};
+
+type CacheDriverConfig =
+  | MemoryCacheDriverConfig
+  | RedisCacheDriverConfig
+  | MemcachedCacheDriverConfig
+  | FileCacheDriverConfig;
+
+type CacheDrivers = {
+  memory: MemoryCacheDriverConfig;
+  redis: RedisCacheDriverConfig;
+  memcached: MemcachedCacheDriverConfig;
+  file: FileCacheDriverConfig;
+};
+
+type CacheConfigInput = {
+  default: string;
+  drivers: CacheDrivers;
+};
+
+const getCacheDriver = (config: CacheConfigInput): CacheDriverConfig => {
+  const defaultDriver = config.default;
+
+  if (Object.prototype.hasOwnProperty.call(config.drivers, defaultDriver)) {
+    const driverName = defaultDriver as keyof CacheDrivers;
+    return config.drivers[driverName];
+  }
+
+  return config.drivers.memory;
+};
+
+const cacheConfigObj = {
+  /**
+   * Default cache driver
+   */
+  default: Env.get('CACHE_DRIVER', 'memory'),
+
+  /**
+   * Cache drivers
+   */
+  drivers: {
+    memory: {
+      driver: 'memory' as const,
+      ttl: Env.getInt('CACHE_MEMORY_TTL', 3600),
+    },
+    redis: {
+      driver: 'redis' as const,
+      host: Env.get('REDIS_HOST', 'localhost'),
+      port: Env.getInt('REDIS_PORT', 6379),
+      password: Env.get('REDIS_PASSWORD'),
+      database: Env.getInt('REDIS_DB', 0),
+      ttl: Env.getInt('CACHE_REDIS_TTL', 3600),
+    },
+    memcached: {
+      driver: 'memcached' as const,
+      servers: Env.get('MEMCACHED_SERVERS', 'localhost:11211').split(','),
+      ttl: Env.getInt('CACHE_MEMCACHED_TTL', 3600),
+    },
+    file: {
+      driver: 'file' as const,
+      path: Env.get('CACHE_FILE_PATH', 'storage/cache'),
+      ttl: Env.getInt('CACHE_FILE_TTL', 3600),
+    },
+  },
+
+  /**
+   * Get cache driver config
+   */
+  getDriver(): CacheDriverConfig {
+    return getCacheDriver(this);
+  },
+
+  /**
+   * Key prefix for all cache keys
+   */
+  keyPrefix: Env.get('CACHE_KEY_PREFIX', 'zintrust:'),
+
+  /**
+   * Default cache TTL (seconds)
+   */
+  ttl: Env.getInt('CACHE_DEFAULT_TTL', 3600),
+};
+
+export const cacheConfig = Object.freeze(cacheConfigObj);
+export type CacheConfig = typeof cacheConfig;

package/src/templates/project/basic/config/constants.ts.tpl

@@ -0,0 +1,70 @@
+/**
+ * Framework Constants
+ * Centralized string literals to prevent duplication (SonarQube S1192)
+ * Sealed namespace for immutability
+ */
+
+const HTTP_HEADERS = {
+  CONTENT_TYPE: 'Content-Type',
+  ACCEPT: 'Accept',
+  AUTHORIZATION: 'Authorization',
+  X_TRACE_ID: 'X-Trace-Id',
+  X_SERVICE_CALL: 'X-Service-Call',
+  X_POWERED_BY: 'X-Powered-By',
+  X_CONTENT_TYPE_OPTIONS: 'X-Content-Type-Options',
+  X_FRAME_OPTIONS: 'X-Frame-Options',
+  X_XSS_PROTECTION: 'X-XSS-Protection',
+  REFERRER_POLICY: 'Referrer-Policy',
+  CONTENT_SECURITY_POLICY: 'Content-Security-Policy',
+} as const;
+
+const MIME_TYPES = {
+  JSON: 'application/json',
+  HTML: 'text/html',
+  TEXT: 'text/plain',
+  JS: 'text/javascript',
+  CSS: 'text/css',
+  PNG: 'image/png',
+  JPG: 'image/jpg',
+  GIF: 'image/gif',
+  SVG: 'image/svg+xml',
+  WAV: 'audio/wav',
+  MP4: 'video/mp4',
+  WOFF: 'application/font-woff',
+  TTF: 'application/font-ttf',
+  EOT: 'application/vnd.ms-fontobject',
+  OTF: 'application/font-otf',
+  WASM: 'application/wasm',
+} as const;
+
+const ENV_KEYS = {
+  NODE_ENV: 'NODE_ENV',
+  PORT: 'PORT',
+  HOST: 'HOST',
+  APP_NAME: 'APP_NAME',
+  DB_CONNECTION: 'DB_CONNECTION',
+  DB_HOST: 'DB_HOST',
+  DB_PORT: 'DB_PORT',
+  DB_DATABASE: 'DB_DATABASE',
+  DB_USERNAME: 'DB_USERNAME',
+  DB_PASSWORD: 'DB_PASSWORD', // NOSONARQUBE
+} as const;
+
+const DEFAULTS = {
+  CONNECTION: 'default',
+  DOMAIN: 'default',
+  NAMESPACE: 'default',
+} as const;
+
+/**
+ * Constants namespace - sealed for immutability
+ */
+export const Constants = Object.freeze({
+  HTTP_HEADERS,
+  MIME_TYPES,
+  ENV_KEYS,
+  DEFAULTS,
+});
+
+// Re-export for backward compatibility
+export { DEFAULTS, ENV_KEYS, HTTP_HEADERS, MIME_TYPES };

package/src/templates/project/basic/config/database.ts.tpl

@@ -0,0 +1,152 @@
+/**
+ * Database Configuration
+ * Database connections and pooling settings
+ * Sealed namespace for immutability
+ */
+
+import { Env } from '@config/env';
+
+type SqliteConnectionConfig = {
+  driver: 'sqlite';
+  database: string;
+  migrations: string;
+};
+
+type PostgresqlConnectionConfig = {
+  driver: 'postgresql';
+  host: string;
+  port: number;
+  database: string;
+  username: string;
+  password: string;
+  ssl: boolean;
+  pooling: {
+    enabled: boolean;
+    min: number;
+    max: number;
+    idleTimeout: number;
+    connectionTimeout: number;
+  };
+};
+
+type MysqlConnectionConfig = {
+  driver: 'mysql';
+  host: string;
+  port: number;
+  database: string;
+  username: string;
+  password: string;
+  pooling: {
+    enabled: boolean;
+    min: number;
+    max: number;
+  };
+};
+
+type DatabaseConnections = {
+  sqlite: SqliteConnectionConfig;
+  postgresql: PostgresqlConnectionConfig;
+  mysql: MysqlConnectionConfig;
+};
+
+type DatabaseConnectionName = keyof DatabaseConnections;
+type DatabaseConnectionConfig = DatabaseConnections[DatabaseConnectionName];
+
+type DatabaseConfigShape = {
+  default: DatabaseConnectionName;
+  connections: DatabaseConnections;
+};
+
+const isDatabaseConnectionName = (value: string): value is DatabaseConnectionName => {
+  return value === 'sqlite' || value === 'postgresql' || value === 'mysql';
+};
+
+const getDefaultConnection = (): DatabaseConnectionName => {
+  const value = Env.DB_CONNECTION;
+  return isDatabaseConnectionName(value) ? value : 'sqlite';
+};
+
+const getDatabaseConnection = (config: DatabaseConfigShape): DatabaseConnectionConfig => {
+  const connName: DatabaseConnectionName = config.default;
+  return config.connections[connName];
+};
+
+const databaseConfigObj = {
+  /**
+   * Default database connection
+   */
+  default: getDefaultConnection(),
+
+  /**
+   * Database connections
+   */
+  connections: {
+    sqlite: {
+      driver: 'sqlite' as const,
+      database: Env.DB_DATABASE,
+      migrations: 'database/migrations',
+    },
+    postgresql: {
+      driver: 'postgresql' as const,
+      host: Env.DB_HOST,
+      port: Env.DB_PORT,
+      database: Env.DB_DATABASE,
+      username: Env.DB_USERNAME,
+      password: Env.DB_PASSWORD,
+      ssl: Env.getBool('DB_SSL', false),
+      pooling: {
+        enabled: Env.getBool('DB_POOLING', true),
+        min: Env.getInt('DB_POOL_MIN', 5),
+        max: Env.getInt('DB_POOL_MAX', 20),
+        idleTimeout: Env.getInt('DB_IDLE_TIMEOUT', 30000),
+        connectionTimeout: Env.getInt('DB_CONNECTION_TIMEOUT', 10000),
+      },
+    },
+    mysql: {
+      driver: 'mysql' as const,
+      host: Env.DB_HOST,
+      port: Env.DB_PORT,
+      database: Env.DB_DATABASE,
+      username: Env.DB_USERNAME,
+      password: Env.DB_PASSWORD,
+      pooling: {
+        enabled: Env.getBool('DB_POOLING', true),
+        min: Env.getInt('DB_POOL_MIN', 5),
+        max: Env.getInt('DB_POOL_MAX', 20),
+      },
+    },
+  },
+
+  /**
+   * Get current connection config
+   */
+  getConnection(this: DatabaseConfigShape): DatabaseConnectionConfig {
+    return getDatabaseConnection(this);
+  },
+
+  /**
+   * Enable query logging
+   */
+  logging: {
+    enabled: Env.DEBUG,
+    level: Env.get('DB_LOG_LEVEL', 'debug'),
+  },
+
+  /**
+   * Migration settings
+   */
+  migrations: {
+    directory: 'database/migrations',
+    extension: Env.get('DB_MIGRATION_EXT', '.ts'),
+  },
+
+  /**
+   * Seeding settings
+   */
+  seeders: {
+    directory: 'database/seeders',
+  },
+};
+
+export const databaseConfig = Object.freeze(databaseConfigObj);
+export type DatabaseConfig = typeof databaseConfig;

package/src/templates/project/basic/config/env.ts.tpl

@@ -0,0 +1,148 @@
+/**
+ * Environment Configuration
+ * Type-safe access to environment variables
+ *
+ * Sealed namespace pattern - all exports through Env namespace
+ * Safe for both Node.js and serverless runtimes (Cloudflare Workers, Deno, Lambda)
+ */
+
+type ProcessLike = {
+  env?: Record<string, string | undefined>;
+  execPath?: string;
+  platform?: string;
+};
+
+const getProcessLike = (): ProcessLike | undefined => {
+  return typeof process === 'undefined' ? undefined : (process as unknown as ProcessLike);
+};
+
+const dirnameFromExecPath = (execPath: string, platform?: string): string => {
+  const separator = platform === 'win32' ? '\\' : '/';
+  const lastSep = execPath.lastIndexOf(separator);
+  if (lastSep <= 0) return '';
+  return execPath.slice(0, lastSep);
+};
+
+// Private helper functions
+const get = (key: string, defaultValue?: string): string => {
+  const proc = getProcessLike();
+  const env = proc?.env ?? {};
+  return env[key] ?? defaultValue ?? '';
+};
+
+const getInt = (key: string, defaultValue?: number): number => {
+  const proc = getProcessLike();
+  const env = proc?.env ?? {};
+  const value = env[key];
+  if (value === undefined || value === null) return defaultValue ?? 0;
+  return Number.parseInt(value, 10);
+};
+
+const getBool = (key: string, defaultValue?: boolean): boolean => {
+  const proc = getProcessLike();
+  const env = proc?.env ?? {};
+  const value = env[key];
+  if (value === undefined || value === null) return defaultValue ?? false;
+  return value.toLowerCase() === 'true' || value === '1';
+};
+
+const getDefaultLogLevel = (): 'debug' | 'info' | 'warn' | 'error' => {
+  const NODE_ENV_VALUE = get('NODE_ENV', 'development');
+  if (NODE_ENV_VALUE === 'production') return 'info';
+  if (NODE_ENV_VALUE === 'testing') return 'error';
+  return 'debug';
+};
+
+// Sealed namespace with all environment configuration
+export const Env = Object.freeze({
+  // Helper functions
+  get,
+  getInt,
+  getBool,
+
+  // Core
+  NODE_ENV: get('NODE_ENV', 'development'),
+  PORT: getInt('APP_PORT', 3000),
+  HOST: get('HOST', 'localhost'),
+  APP_NAME: get('APP_NAME', 'ZinTrust'),
+  APP_KEY: get('APP_KEY', ''),
+
+  // Database
+  DB_CONNECTION: get('DB_CONNECTION', 'sqlite'),
+  DB_HOST: get('DB_HOST', 'localhost'),
+  DB_PORT: getInt('DB_PORT', 5432),
+  DB_DATABASE: get('DB_DATABASE', '@zintrust/core'),
+  DB_USERNAME: get('DB_USERNAME', 'postgres'),
+  DB_PASSWORD: get('DB_PASSWORD', ''),
+  DB_READ_HOSTS: get('DB_READ_HOSTS', ''),
+
+  // Cloudflare
+  D1_DATABASE_ID: get('D1_DATABASE_ID'),
+  KV_NAMESPACE_ID: get('KV_NAMESPACE_ID'),
+
+  // Cache
+  CACHE_DRIVER: get('CACHE_DRIVER', 'memory'),
+  REDIS_HOST: get('REDIS_HOST', 'localhost'),
+  REDIS_PORT: getInt('REDIS_PORT', 6379),
+  REDIS_PASSWORD: get('REDIS_PASSWORD', ''),
+  MONGO_URI: get('MONGO_URI'),
+  MONGO_DB: get('MONGO_DB', 'zintrust_cache'),
+
+  // AWS
+  AWS_REGION: get('AWS_REGION', 'us-east-1'),
+  AWS_LAMBDA_FUNCTION_NAME: get('AWS_LAMBDA_FUNCTION_NAME'),
+  AWS_LAMBDA_FUNCTION_VERSION: get('AWS_LAMBDA_FUNCTION_VERSION'),
+  AWS_EXECUTION_ENV: get('AWS_EXECUTION_ENV'),
+  LAMBDA_TASK_ROOT: get('LAMBDA_TASK_ROOT'),
+
+  // Microservices
+  MICROSERVICES: get('MICROSERVICES'),
+  SERVICES: get('SERVICES'),
+  MICROSERVICES_TRACING: getBool('MICROSERVICES_TRACING'),
+  MICROSERVICES_TRACING_RATE: Number.parseFloat(get('MICROSERVICES_TRACING_RATE', '1.0')),
+  DATABASE_ISOLATION: get('DATABASE_ISOLATION', 'shared'),
+  SERVICE_API_KEY: get('SERVICE_API_KEY'),
+  SERVICE_JWT_SECRET: get('SERVICE_JWT_SECRET'),
+
+  // Security
+  DEBUG: getBool('DEBUG', false),
+  ENABLE_MICROSERVICES: getBool('ENABLE_MICROSERVICES', false),
+  TOKEN_TTL: getInt('TOKEN_TTL', 3600000),
+  TOKEN_LENGTH: getInt('TOKEN_LENGTH', 32),
+
+  // Deployment
+  ENVIRONMENT: get('ENVIRONMENT', 'development'),
+  REQUEST_TIMEOUT: getInt('REQUEST_TIMEOUT', 30000),
+  MAX_BODY_SIZE: getInt('MAX_BODY_SIZE', 10485760),
+
+  // Logging
+  LOG_LEVEL: get('LOG_LEVEL', getDefaultLogLevel()) as 'debug' | 'info' | 'warn' | 'error',
+  DISABLE_LOGGING: getBool('DISABLE_LOGGING', false),
+
+  // Paths (safely constructed for Node.js environments)
+  NODE_BIN_DIR: (() => {
+    try {
+      const proc = getProcessLike();
+      if (proc?.execPath === null || proc?.execPath === undefined) return '';
+      return dirnameFromExecPath(proc.execPath, proc.platform);
+    } catch {
+      // Fallback for non-Node environments
+      return '';
+    }
+  })(),
+  SAFE_PATH: (() => {
+    try {
+      const proc = getProcessLike();
+      if (proc?.execPath === null || proc?.execPath === undefined) return '';
+
+      const binDir = dirnameFromExecPath(proc.execPath, proc.platform);
+      if (proc.platform === 'win32') {
+        return [String.raw`C:\Windows\System32`, String.raw`C:\Windows`, binDir].join(';');
+      }
+      return ['/usr/bin', '/bin', '/usr/sbin', '/sbin', binDir].join(':');
+    } catch {
+      // Fallback for non-Node environments
+      return '';
+    }
+  })(),
+});

package/src/templates/project/basic/config/features.ts.tpl

@@ -0,0 +1,57 @@
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+
+/**
+ * Feature Flags State
+ * Internal state managed by the module
+ */
+let _rawQueryEnabled = false;
+
+/**
+ * Feature Flags - Controls access to advanced/experimental features
+ * Sealed namespace for immutability
+ */
+export const FeatureFlags = Object.freeze({
+  /**
+   * Initialize all feature flags from environment
+   * Called once during application bootstrap
+   */
+  initialize(): void {
+    _rawQueryEnabled = Env.get('USE_RAW_QRY') === 'true';
+
+    if (_rawQueryEnabled) {
+      Logger.warn(
+        '⚠️  FEATURE FLAG ENABLED: Raw SQL Queries are now available via adapter.rawQuery()'
+      );
+      Logger.warn('⚠️  This bypasses QueryBuilder safety - use only when necessary');
+      Logger.warn('⚠️  Ensure parameters are properly bound to prevent SQL injection');
+    } else {
+      Logger.info('🔒 Raw SQL Queries are DISABLED (default, recommended for production)');
+    }
+  },
+
+  /**
+   * Check if raw queries are enabled
+   * Returns cached flag value (no environment lookup)
+   */
+  isRawQueryEnabled(): boolean {
+    return _rawQueryEnabled;
+  },
+
+  /**
+   * Reset flags (primarily for testing)
+   */
+  reset(): void {
+    _rawQueryEnabled = false;
+  },
+
+  /**
+   * Set raw query enabled state
+   * Primarily for testing to avoid 'as any' type casting
+   */
+  setRawQueryEnabled(enabled: boolean): void {
+    _rawQueryEnabled = enabled;
+  },
+});
+
+export default FeatureFlags;

package/src/templates/project/basic/config/index.ts.tpl

@@ -0,0 +1,36 @@
+/**
+ * Configuration Exports
+ * Central export point for all configuration
+ */
+
+import { appConfig } from '@config/app';
+import { cacheConfig } from '@config/cache';
+import { databaseConfig } from '@config/database';
+import { microservicesConfig } from '@config/microservices';
+import { queueConfig } from '@config/queue';
+import { securityConfig } from '@config/security';
+import { storageConfig } from '@config/storage';
+
+export { appConfig, type AppConfig } from '@config/app';
+export { cacheConfig, type CacheConfig } from '@config/cache';
+export { databaseConfig, type DatabaseConfig } from '@config/database';
+export { microservicesConfig, type MicroservicesConfig } from '@config/microservices';
+export { queueConfig, type QueueConfig } from '@config/queue';
+export { securityConfig } from '@config/security';
+export { storageConfig, type StorageConfig } from '@config/storage';
+
+/**
+ * Combined configuration object
+ * Sealed namespace for immutability
+ */
+export const config = Object.freeze({
+  app: appConfig,
+  database: databaseConfig,
+  storage: storageConfig,
+  security: securityConfig,
+  microservices: microservicesConfig,
+  cache: cacheConfig,
+  queue: queueConfig,
+} as const);
+
+export type Config = typeof config;

package/src/templates/project/basic/config/logger.ts.tpl

@@ -0,0 +1,95 @@
+/**
+ * Logger utility - Central logging configuration
+ * Sealed namespace pattern - all exports through Logger namespace
+ * Replaces console.* calls throughout the codebase
+ */
+import { Env } from '@config/env';
+
+interface ILogger {
+  debug(message: string, data?: unknown, category?: string): void;
+  info(message: string, data?: unknown, category?: string): void;
+  warn(message: string, data?: unknown, category?: string): void;
+  error(message: string, error?: unknown, category?: string): void;
+  fatal(message: string, error?: unknown, category?: string): void;
+}
+
+const isDevelopment = Env.NODE_ENV === 'development' || Env.NODE_ENV === undefined;
+const isProduction = Env.NODE_ENV === 'production';
+
+/**
+ * Helper to extract error message from unknown error type
+ */
+const getErrorMessage = (error?: unknown): string => {
+  if (error === undefined) {
+    return '';
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+};
+
+// Private helper functions
+const logDebug = (message: string, data?: unknown, category?: string): void => {
+  String(category);
+  if (isDevelopment) {
+    console.debug(`[DEBUG] ${message}`, data ?? ''); // eslint-disable-line no-console
+  }
+};
+
+const logInfo = (message: string, data?: unknown, category?: string): void => {
+  String(category);
+  console.log(`[INFO] ${message}`, data ?? ''); // eslint-disable-line no-console
+};
+
+const logWarn = (message: string, data?: unknown, category?: string): void => {
+  String(category);
+  console.warn(`[WARN] ${message}`, data ?? ''); // eslint-disable-line no-console
+};
+
+const logError = (message: string, error?: unknown, category?: string): void => {
+  const errorMessage = getErrorMessage(error);
+  String(category);
+  console.error(`[ERROR] ${message}`, errorMessage); // eslint-disable-line no-console
+};
+
+const logFatal = (message: string, error?: unknown, category?: string): void => {
+  const errorMessage = getErrorMessage(error);
+  String(category);
+  console.error(`[FATAL] ${message}`, errorMessage); // eslint-disable-line no-console
+  if (isProduction && typeof process !== 'undefined') {
+    process.exit(1);
+  }
+};
+
+const createLoggerScope = (scope: string): ILogger => {
+  return {
+    debug(message: string, data?: unknown): void {
+      logDebug(`[${scope}] ${message}`, data, scope);
+    },
+    info(message: string, data?: unknown): void {
+      logInfo(`[${scope}] ${message}`, data, scope);
+    },
+    warn(message: string, data?: unknown): void {
+      logWarn(`[${scope}] ${message}`, data, scope);
+    },
+    error(message: string, error?: unknown): void {
+      logError(`[${scope}] ${message}`, error, scope);
+    },
+    fatal(message: string, error?: unknown): void {
+      logFatal(`[${scope}] ${message}`, error, scope);
+    },
+  };
+};
+
+// Sealed namespace with all logger functionality
+export const Logger = Object.freeze({
+  debug: logDebug,
+  info: logInfo,
+  warn: logWarn,
+  error: logError,
+  fatal: logFatal,
+  scope: createLoggerScope,
+});
+
+export default Logger;