@zintrust/core 0.1.19 → 0.1.21

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

@@ -1,268 +1,9 @@
-import { appConfig } from '@zintrust/core';
-import type { StartupConfigValidationError, StartupConfigValidationResult } from '@zintrust/core';
-import { ErrorFactory } from '@zintrust/core';
-
-const isSensitiveKey = (key: string): boolean => {
-  const normalized = key.toLowerCase();
-  return (
-    normalized.includes('password') ||
-    normalized.includes('secret') ||
-    normalized.includes('token') ||
-    normalized.includes('key') ||
-    normalized.includes('authorization')
-  );
-};
-
-const redactValue = (key: string, value: unknown): unknown => {
-  return isSensitiveKey(key) ? '<redacted>' : value;
-};
-
-const pushError = (
-  errors: StartupConfigValidationError[],
-  key: string,
-  value: unknown,
-  message: string
-): void => {
-  errors.push({ key, value: redactValue(key, value), message });
-};
-
-const validateEnum = (
-  errors: StartupConfigValidationError[],
-  key: string,
-  value: string,
-  allowed: readonly string[]
-): void => {
-  if (!allowed.includes(value)) {
-    pushError(errors, key, value, `${key} must be one of: ${allowed.join(', ')}`);
-  }
-};
-
-const validateIntRange = (
-  errors: StartupConfigValidationError[],
-  key: string,
-  value: number,
-  min: number,
-  max: number
-): void => {
-  if (Number.isNaN(value)) {
-    pushError(errors, key, value, `${key} must be a valid integer`);
-    return;
-  }
-
-  if (value < min || value > max) {
-    pushError(errors, key, value, `${key} must be between ${min} and ${max}`);
-  }
-};
-
-const validatePositiveInt = (
-  errors: StartupConfigValidationError[],
-  key: string,
-  value: number
-): void => {
-  if (Number.isNaN(value)) {
-    pushError(errors, key, value, `${key} must be a valid integer`);
-    return;
-  }
-
-  if (value <= 0) {
-    pushError(errors, key, value, `${key} must be greater than 0`);
-  }
-};
-
-type ProcessLike = {
-  env?: Record<string, string | undefined>;
-};
-
-const getProcessLike = (): ProcessLike | undefined => {
-  return typeof process === 'undefined' ? undefined : (process as unknown as ProcessLike);
-};
-
-const getEnvString = (key: string, defaultValue: string): string => {
-  const proc = getProcessLike();
-  const env = proc?.env ?? {};
-  return env[key] ?? defaultValue;
-};
-
-const getEnvOptionalString = (key: string): string | undefined => {
-  const proc = getProcessLike();
-  const env = proc?.env ?? {};
-  const value = env[key];
-  if (typeof value !== 'string') return undefined;
-  const trimmed = value.trim();
-  return trimmed === '' ? undefined : trimmed;
-};
-
-const getEnvBoolLoose = (key: string, defaultValue: boolean): boolean => {
-  const raw = getEnvOptionalString(key);
-  if (raw === undefined) return defaultValue;
-  const normalized = raw.toLowerCase();
-  return normalized === 'true' || normalized === '1' || normalized === 'yes' || normalized === 'on';
-};
-
-const getEnvInt = (key: string, defaultValue: number): number => {
-  const raw = getEnvString(key, String(defaultValue));
-  return Number.parseInt(raw, 10);
-};
-
-type RequireEnvStringOptions = {
-  aliases?: readonly string[];
-  requiredMessage?: string;
-  minLength?: number;
-  minLengthMessage?: string;
-};
-
-const requireEnvString = (
-  errors: StartupConfigValidationError[],
-  key: string,
-  options: RequireEnvStringOptions = {}
-): string | undefined => {
-  const value =
-    getEnvOptionalString(key) ??
-    (options.aliases ?? []).reduce<string | undefined>((found, alias) => {
-      if (found !== undefined) return found;
-      return getEnvOptionalString(alias);
-    }, undefined);
-
-  if (value === undefined) {
-    pushError(errors, key, value, options.requiredMessage ?? `${key} is required`);
-    return undefined;
-  }
-
-  if (options.minLength !== undefined && value.length < options.minLength) {
-    pushError(
-      errors,
-      key,
-      value,
-      options.minLengthMessage ?? `${key} must be at least ${options.minLength} characters`
-    );
-  }
-
-  return value;
-};
-
-const validateSqliteDbFileRequired = (
-  errors: StartupConfigValidationError[],
-  dbConnection: string | undefined
-): void => {
-  // sqlite convenience: accept DB_DATABASE or DB_PATH
-  if ((dbConnection ?? '').toLowerCase() !== 'sqlite') return;
-
-  const dbFile = getEnvOptionalString('DB_DATABASE') ?? getEnvOptionalString('DB_PATH');
-  if (dbFile === undefined) {
-    pushError(errors, 'DB_DATABASE', dbFile, 'DB_DATABASE (or DB_PATH) is required for sqlite');
-  }
-};
-
-const validateStrictRequiredEnv = (errors: StartupConfigValidationError[]): void => {
-  const requireEnv = getEnvBoolLoose('STARTUP_REQUIRE_ENV', false);
-  if (!requireEnv) return;
-
-  requireEnvString(errors, 'NODE_ENV');
-  requireEnvString(errors, 'APP_NAME');
-  requireEnvString(errors, 'HOST');
-
-  const portRaw = requireEnvString(errors, 'PORT', {
-    aliases: ['APP_PORT'],
-    requiredMessage: 'PORT (or APP_PORT) is required',
-  });
-  if (portRaw !== undefined) {
-    const port = Number.parseInt(portRaw, 10);
-    validateIntRange(errors, 'PORT', port, 1, 65535);
-  }
-
-  const dbConnection = requireEnvString(errors, 'DB_CONNECTION');
-
-  requireEnvString(errors, 'APP_KEY', { minLength: 16 });
-  requireEnvString(errors, 'LOG_LEVEL');
-  requireEnvString(errors, 'LOG_CHANNEL');
-
-  validateSqliteDbFileRequired(errors, dbConnection);
-};
-
-const validateNodeEnv = (errors: StartupConfigValidationError[]): void => {
-  const nodeEnv = getEnvString('NODE_ENV', 'development');
-  validateEnum(errors, 'NODE_ENV', nodeEnv, ['development', 'production', 'testing', 'test']);
-};
-
-const validatePort = (errors: StartupConfigValidationError[]): void => {
-  // Port can be provided as PORT or APP_PORT. In non-strict mode we keep defaults.
-  const portFromPort = getEnvOptionalString('PORT');
-  const portFromAppPort = getEnvOptionalString('APP_PORT');
-  const portRaw = portFromPort ?? portFromAppPort;
-
-  if (portRaw === undefined) {
-    const appPort = getEnvInt('APP_PORT', 3000);
-    validateIntRange(errors, 'APP_PORT', appPort, 1, 65535);
-    return;
-  }
-
-  const parsed = Number.parseInt(portRaw, 10);
-  const key = portFromPort === undefined ? 'APP_PORT' : 'PORT';
-  validateIntRange(errors, key, parsed, 1, 65535);
-};
-
-const validateLogging = (errors: StartupConfigValidationError[]): void => {
-  const logFormat = getEnvString('LOG_FORMAT', 'text');
-  validateEnum(errors, 'LOG_FORMAT', logFormat, ['text', 'json']);
-
-  const logLevel = getEnvString('LOG_LEVEL', 'debug');
-  validateEnum(errors, 'LOG_LEVEL', logLevel, ['debug', 'info', 'warn', 'error']);
-
-  // Optional (but validated when provided): LOG_CHANNEL (starter apps often use this)
-  const logChannel = getEnvOptionalString('LOG_CHANNEL');
-  if (logChannel !== undefined) {
-    validateEnum(errors, 'LOG_CHANNEL', logChannel, ['console', 'file', 'all']);
-  }
-};
-
-const validateRotationAndTimeout = (errors: StartupConfigValidationError[]): void => {
-  const logRotationSize = getEnvInt('LOG_ROTATION_SIZE', 10485760);
-  validatePositiveInt(errors, 'LOG_ROTATION_SIZE', logRotationSize);
-
-  const logRotationDays = getEnvInt('LOG_ROTATION_DAYS', 7);
-  validatePositiveInt(errors, 'LOG_ROTATION_DAYS', logRotationDays);
-
-  const startupHealthTimeoutMs = getEnvInt('STARTUP_HEALTH_TIMEOUT_MS', 2500);
-  validatePositiveInt(errors, 'STARTUP_HEALTH_TIMEOUT_MS', startupHealthTimeoutMs);
-};
-
-const validateProductionAppKey = (errors: StartupConfigValidationError[]): void => {
-  if (!appConfig.isProduction()) return;
-
-  const appKey = getEnvString('APP_KEY', '');
-  if (appKey.trim().length < 16) {
-    pushError(
-      errors,
-      'APP_KEY',
-      appKey,
-      'APP_KEY must be set and at least 16 characters in production'
-    );
-  }
-};
-
-export const StartupConfigValidator = Object.freeze({
-  validate(): StartupConfigValidationResult {
-    const errors: StartupConfigValidationError[] = [];
-
-    validateStrictRequiredEnv(errors);
-
-    validateNodeEnv(errors);
-    validatePort(errors);
-    validateLogging(errors);
-    validateRotationAndTimeout(errors);
-    validateProductionAppKey(errors);
-
-    return { valid: errors.length === 0, errors };
-  },
-
-  assertValid(): void {
-    const result = StartupConfigValidator.validate();
-    if (result.valid) return;
-
-    throw ErrorFactory.createConfigError('Invalid startup configuration', {
-      errors: result.errors,
-    });
-  },
-});
-
-export default StartupConfigValidator;
+/**
+ * Startup Config Validator (template)
+ *
+ * Keep this file declarative:
+ * - Core owns validation logic.
+ */
+
+export { StartupConfigValidator } from '@zintrust/core';
+export { StartupConfigValidator as default } from '@zintrust/core';

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

@@ -1,162 +1,22 @@
 /**
- * Application Configuration
- * Core application settings
- * Sealed namespace for immutability
+ * Application Configuration (template)
+ *
+ * Keep this file declarative:
+ * - Core owns env parsing/default logic.
+ * - Projects can override values by editing `appConfigObj`.
  */
 
-import { Env } from '@zintrust/core';
-import type { Environment, ProcessLike, StartMode } from '@zintrust/core';
+import { appConfig as coreAppConfig } from '@zintrust/core';
 
-const getProcessLike = (): ProcessLike | undefined => {
-  return typeof process === 'undefined' ? undefined : (process as unknown as ProcessLike);
-};
+type AppConfigShape = typeof coreAppConfig;
 
-const readEnvString = (key: string, defaultValue: string = ''): string => {
-  const anyEnv = Env as unknown as { get?: unknown };
-  if (typeof anyEnv.get === 'function') {
-    return (anyEnv.get as (k: string, d?: string) => string)(key, defaultValue);
-  }
+export const appConfigObj = {
+  ...coreAppConfig,
+} satisfies AppConfigShape;
 
-  const proc = getProcessLike();
-  const raw = proc?.env?.[key];
-  return raw ?? defaultValue;
-};
+export const appConfig = appConfigObj;
 
-const readEnvInt = (key: string, defaultValue: number): number => {
-  const anyEnv = Env as unknown as { getInt?: unknown };
-  if (typeof anyEnv.getInt === 'function') {
-    return (anyEnv.getInt as (k: string, d?: number) => number)(key, defaultValue);
-  }
-
-  const raw = readEnvString(key, String(defaultValue));
-  const parsed = Number.parseInt(raw, 10);
-  return Number.isNaN(parsed) ? defaultValue : parsed;
-};
-
-const readEnvBool = (key: string, defaultValue: boolean): boolean => {
-  const anyEnv = Env as unknown as { getBool?: unknown };
-  if (typeof anyEnv.getBool === 'function') {
-    return (anyEnv.getBool as (k: string, d?: boolean) => boolean)(key, defaultValue);
-  }
-
-  const raw = readEnvString(key, defaultValue ? 'true' : 'false');
-  return raw.toLowerCase() === 'true' || raw === '1';
-};
-
-const getSafeEnv = (): NodeJS.ProcessEnv => {
-  const baseEnv: Partial<NodeJS.ProcessEnv> = typeof process === 'undefined' ? {} : process.env;
-
-  return {
-    ...(baseEnv as NodeJS.ProcessEnv),
-
-    // Ensure required keys exist (env.d.ts augments ProcessEnv with required fields)
-    NODE_ENV:
-      baseEnv.NODE_ENV ??
-      (readEnvString('NODE_ENV', 'development') as NodeJS.ProcessEnv['NODE_ENV']),
-    USE_RAW_QRY: baseEnv.USE_RAW_QRY ?? (readEnvString('USE_RAW_QRY', '') || undefined),
-    SERVICE_API_KEY: baseEnv.SERVICE_API_KEY ?? readEnvString('SERVICE_API_KEY', ''),
-    SERVICE_JWT_SECRET: baseEnv.SERVICE_JWT_SECRET ?? readEnvString('SERVICE_JWT_SECRET', ''),
-    BASE_URL: baseEnv['BASE_URL'] ?? readEnvString('BASE_URL', ''),
-    MODE: baseEnv['MODE'] ?? readEnvString('MODE', ''),
-
-    // Hardening for child-process usage
-    PATH:
-      typeof (Env as unknown as { SAFE_PATH?: unknown }).SAFE_PATH === 'string'
-        ? (Env as unknown as { SAFE_PATH: string }).SAFE_PATH
-        : (baseEnv['PATH'] ?? ''),
-    npm_config_scripts_prepend_node_path: 'true',
-  };
-};
-
-const normalizeMode = (): StartMode => {
-  const value = (
-    typeof (Env as unknown as { NODE_ENV?: unknown }).NODE_ENV === 'string'
-      ? (Env as unknown as { NODE_ENV: string }).NODE_ENV
-      : readEnvString('NODE_ENV', 'development')
-  ) as Environment;
-  if (value === 'production' || value === 'pro' || value === 'prod') return 'production';
-  if (value === 'testing' || value === 'test') return 'testing';
-  return 'development';
-};
-
-const appConfigObj = {
-  /**
-   * Application name
-   */
-  name:
-    typeof (Env as unknown as { APP_NAME?: unknown }).APP_NAME === 'string'
-      ? (Env as unknown as { APP_NAME: string }).APP_NAME
-      : readEnvString('APP_NAME', 'ZinTrust'),
-
-  /**
-   * Application environment
-   */
-  environment: normalizeMode(),
-
-  /**
-   * Application port
-   */
-  port:
-    typeof (Env as unknown as { PORT?: unknown }).PORT === 'number'
-      ? (Env as unknown as { PORT: number }).PORT
-      : readEnvInt('PORT', readEnvInt('APP_PORT', 3000)),
-
-  /**
-   * Application host
-   */
-  host:
-    typeof (Env as unknown as { HOST?: unknown }).HOST === 'string'
-      ? (Env as unknown as { HOST: string }).HOST
-      : readEnvString('HOST', 'localhost'),
-
-  /**
-   * Is development environment
-   */
-  isDevelopment(): boolean {
-    return this.environment === 'development';
-  },
-
-  /**
-   * Is production environment
-   */
-  isProduction(): boolean {
-    return this.environment === 'production';
-  },
-
-  /**
-   * Is testing environment
-   */
-  isTesting(): boolean {
-    return this.environment === 'testing';
-  },
-
-  /**
-   * Application debug mode
-   */
-  debug:
-    typeof (Env as unknown as { DEBUG?: unknown }).DEBUG === 'boolean'
-      ? (Env as unknown as { DEBUG: boolean }).DEBUG
-      : readEnvBool('DEBUG', false),
-
-  /**
-   * Application timezone
-   */
-  timezone: readEnvString('APP_TIMEZONE', 'UTC'),
-
-  /**
-   * Request timeout (milliseconds)
-   */
-  requestTimeout: readEnvInt('REQUEST_TIMEOUT', 30000),
-
-  /**
-   * Max request body size
-   */
-  maxBodySize: readEnvString('MAX_BODY_SIZE', '10mb'),
-
-  getSafeEnv,
-} as const;
-
-export const appConfig = Object.freeze(appConfigObj);
-export { getSafeEnv };
+// Keep the template API stable
+export const getSafeEnv = appConfig.getSafeEnv;
 
 export type AppConfig = typeof appConfig;

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

@@ -1,136 +1,39 @@
+import { Env, type BroadcastConfigOverrides } from '@zintrust/core';
+
 /**
- * Broadcast Configuration
+ * Broadcast Configuration (default override)
  *
- * Centralizes broadcast driver selection and provider env mappings.
- * Driver selection must be dynamic (tests may mutate process.env).
+ * Keep this file declarative:
+ * - Core owns env parsing/default logic.
+ * - Projects can override config by editing values below.
  */
 
-import  type{
-  BroadcastConfigInput,
-  BroadcastDrivers,
-  InMemoryBroadcastDriverConfig,
-  KnownBroadcastDriverConfig,
-  PusherBroadcastDriverConfig,
-  RedisBroadcastDriverConfig,
-  RedisHttpsBroadcastDriverConfig,
-} from '@zintrust/core';
-import { ErrorFactory,Env } from '@zintrust/core';
-
-const normalizeDriverName = (value: string): string => value.trim().toLowerCase();
-
-const hasOwn = (obj: Record<string, unknown>, key: string): boolean => {
-  return Object.hasOwn(obj, key);
-};
-
-const getDefaultBroadcaster = (drivers: BroadcastDrivers): string => {
-  const envSelectedRaw = Env.get('BROADCAST_CONNECTION', Env.get('BROADCAST_DRIVER', 'inmemory'));
-  const value = normalizeDriverName(envSelectedRaw ?? 'inmemory');
-
-  if (value.length > 0 && hasOwn(drivers, value)) return value;
-
-  if (envSelectedRaw.trim().length > 0) {
-    throw ErrorFactory.createConfigError(`Broadcast driver not configured: ${value}`);
-  }
-
-  return hasOwn(drivers, 'inmemory') ? 'inmemory' : (Object.keys(drivers)[0] ?? 'inmemory');
-};
-
-const getPusherConfig = (): PusherBroadcastDriverConfig => ({
-  driver: 'pusher',
-  appId: Env.get('PUSHER_APP_ID', ''),
-  key: Env.get('PUSHER_APP_KEY', ''),
-  secret: Env.get('PUSHER_APP_SECRET', ''),
-  cluster: Env.get('PUSHER_APP_CLUSTER', ''),
-  useTLS: Env.getBool('PUSHER_USE_TLS', true),
-});
-
-const getRedisConfig = (): RedisBroadcastDriverConfig => ({
-  driver: 'redis',
-  host: Env.get('BROADCAST_REDIS_HOST', Env.get('REDIS_HOST', 'localhost')),
-  port: Env.getInt('BROADCAST_REDIS_PORT', Env.getInt('REDIS_PORT', 6379)),
-  password: Env.get('BROADCAST_REDIS_PASSWORD', Env.get('REDIS_PASSWORD', '')),
-  channelPrefix: Env.get('BROADCAST_CHANNEL_PREFIX', 'broadcast:'),
-});
-
-const getRedisHttpsConfig = (): RedisHttpsBroadcastDriverConfig => ({
-  driver: 'redishttps',
-  endpoint: Env.get('REDIS_HTTPS_ENDPOINT', ''),
-  token: Env.get('REDIS_HTTPS_TOKEN', ''),
-  channelPrefix: Env.get('BROADCAST_CHANNEL_PREFIX', 'broadcast:'),
-});
-
-const getBroadcastDriver = (
-  config: BroadcastConfigInput,
-  name?: string
-): KnownBroadcastDriverConfig => {
-  const selected = normalizeDriverName(String(name ?? config.default));
-  const broadcasterName = selected === 'default' ? normalizeDriverName(config.default) : selected;
-
-  const isExplicitSelection =
-    name !== undefined &&
-    String(name).trim().length > 0 &&
-    normalizeDriverName(String(name)) !== 'default';
-
-  if (broadcasterName.length > 0 && hasOwn(config.drivers, broadcasterName)) {
-    const resolved = (config.drivers as Record<string, KnownBroadcastDriverConfig>)[
-      broadcasterName
-    ];
-    if (resolved !== undefined) return resolved;
-  }
-
-  if (isExplicitSelection) {
-    throw ErrorFactory.createConfigError(`Broadcast driver not configured: ${broadcasterName}`);
-  }
-
-  const fallback = config.drivers['inmemory'] ?? Object.values(config.drivers)[0];
-  if (fallback !== undefined) return fallback;
-
-  throw ErrorFactory.createConfigError('No broadcast drivers are configured');
-};
-
-const broadcastConfigObj = {
-  /**
-   * Default broadcaster name (normalized).
-   */
-  get default(): string {
-    return getDefaultBroadcaster(this.drivers);
-  },
-
-  /**
-   * Broadcast drivers.
-   *
-   * You may add custom named broadcasters (e.g. `ops`, `billing`) that point to any
-   * known driver config.
-   */
+export default {
+  default: Env.get('BROADCAST_CONNECTION', Env.get('BROADCAST_DRIVER', 'inmemory')),
   drivers: {
-    get inmemory(): InMemoryBroadcastDriverConfig {
-      return { driver: 'inmemory' };
+    inmemory: {
+      driver: 'inmemory' as const,
     },
-    get pusher() {
-      return getPusherConfig();
+    pusher: {
+      driver: 'pusher' as const,
+      appId: Env.get('PUSHER_APP_ID', ''),
+      key: Env.get('PUSHER_APP_KEY', ''),
+      secret: Env.get('PUSHER_APP_SECRET', ''),
+      cluster: Env.get('PUSHER_APP_CLUSTER', ''),
+      useTLS: Env.getBool('PUSHER_USE_TLS', true),
     },
-    get redis() {
-      return getRedisConfig();
+    redis: {
+      driver: 'redis' as const,
+      host: Env.get('BROADCAST_REDIS_HOST', Env.get('REDIS_HOST', 'localhost')),
+      port: Env.getInt('BROADCAST_REDIS_PORT', Env.getInt('REDIS_PORT', 6379)),
+      password: Env.get('BROADCAST_REDIS_PASSWORD', Env.get('REDIS_PASSWORD', '')),
+      channelPrefix: Env.get('BROADCAST_CHANNEL_PREFIX', 'broadcast:'),
     },
-    get redishttps() {
-      return getRedisHttpsConfig();
+    redishttps: {
+      driver: 'redishttps' as const,
+      endpoint: Env.get('REDIS_HTTPS_ENDPOINT', ''),
+      token: Env.get('REDIS_HTTPS_TOKEN', ''),
+      channelPrefix: Env.get('BROADCAST_CHANNEL_PREFIX', 'broadcast:'),
     },
-  } satisfies BroadcastDrivers,
-
-  /**
-   * Normalized broadcast driver name for the default broadcaster.
-   */
-  getDriverName(): string {
-    return normalizeDriverName(this.default);
   },
-
-  /**
-   * Get a config object for the currently selected driver.
-   * Defaults to inmemory for unknown/unsupported names.
-   */
-  getDriverConfig(name?: string): KnownBroadcastDriverConfig {
-    return getBroadcastDriver(this, name);
-  },
-} as const;
-
-export default Object.freeze(broadcastConfigObj);
+} satisfies BroadcastConfigOverrides;