@zintrust/core 0.1.18 → 0.1.20

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

@@ -1,35 +1,38 @@
 /**
- * Configuration Exports
+ * Configuration Exports (template)
  * Central export point for all configuration
  */
 
-import { appConfig } from './app';
-import broadcastConfig from './broadcast';
-import { cacheConfig } from './cache';
-import { databaseConfig } from './database';
-import { microservicesConfig } from './microservices';
-import { middlewareConfig } from './middleware';
-import notificationConfig from './notification';
-import { queueConfig } from './queue';
-import { securityConfig } from './security';
-import { storageConfig } from './storage';
+export {
+  appConfig,
+  broadcastConfig,
+  cacheConfig,
+  databaseConfig,
+  microservicesConfig,
+  middlewareConfig,
+  notificationConfig,
+  queueConfig,
+  securityConfig,
+  storageConfig,
+} from '@zintrust/core';
 
-export { appConfig, type AppConfig } from './app';
-export { default as broadcastConfig } from './broadcast';
-export { cacheConfig, type CacheConfig } from './cache';
-export { databaseConfig, type DatabaseConfig } from './database';
-export { microservicesConfig, type MicroservicesConfig } from './microservices';
-export { middlewareConfig } from './middleware';
-export { notificationConfig, type NotificationConfig } from './notification';
-export { queueConfig, type QueueConfig } from './queue';
-export { securityConfig } from './security';
-export { storageConfig, type StorageConfig } from './storage';
+export type {
+  AppConfig,
+  BroadcastConfig,
+  CacheConfig,
+  DatabaseConfig,
+  MicroservicesConfig,
+  MiddlewareConfig,
+  NotificationConfig,
+  QueueConfig,
+  SecurityConfig,
+  StorageConfig,
+} from '@zintrust/core';
 
 /**
  * Combined configuration object
- * Sealed namespace for immutability
  */
-export const config = Object.freeze({
+export const config = {
   app: appConfig,
   broadcast: broadcastConfig,
   database: databaseConfig,
@@ -40,6 +43,6 @@ export const config = Object.freeze({
   microservices: microservicesConfig,
   cache: cacheConfig,
   queue: queueConfig,
-} as const);
+} as const;
 
 export type Config = typeof config;

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

@@ -1,387 +1,11 @@
 /**
  * Logger utility - Central logging configuration
- * Sealed namespace pattern - all exports through Logger namespace
- * Replaces console.* calls throughout the codebase
+ *
+ * Starter projects should use the framework's core Logger.
+ * This keeps templates free of relative imports and ensures logging
+ * behaves consistently across runtimes.
  */
-import { appConfig } from './app';
-import { Env } from './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 = (): boolean => appConfig.isDevelopment();
-const isProduction = (): boolean => appConfig.isProduction();
-
-const getLogFormat = (): string => Env.get('LOG_FORMAT', 'text');
-const isJsonFormat = (value: unknown): value is 'json' => value === 'json';
-
-const SENSITIVE_FIELDS = new Set<string>([
-  'password',
-  'token',
-  'authorization',
-  'secret',
-  'apikey',
-  'api_key',
-  'jwt',
-  'bearer',
-]);
-
-const redactSensitiveData = (data: unknown): unknown => {
-  const seen = new WeakSet<object>();
-
-  const walk = (value: unknown): unknown => {
-    if (Array.isArray(value)) {
-      if (seen.has(value)) return '[Circular]';
-      seen.add(value);
-      return value.map((v) => walk(v));
-    }
-
-    if (typeof value === 'object' && value !== null) {
-      const asObj = value as Record<string, unknown>;
-      if (seen.has(asObj)) return '[Circular]';
-      seen.add(asObj);
-
-      const out: Record<string, unknown> = {};
-      for (const [key, inner] of Object.entries(asObj)) {
-        if (SENSITIVE_FIELDS.has(key.toLowerCase())) {
-          out[key] = '[REDACTED]';
-        } else {
-          out[key] = walk(inner);
-        }
-      }
-      return out;
-    }
-
-    return value;
-  };
-
-  return walk(data);
-};
-
-const safeStringify = (obj: unknown, indent: boolean = false): string => {
-  const seen = new WeakSet<object>();
-  return JSON.stringify(
-    obj,
-    (_key: string, value: unknown) => {
-      if (typeof value === 'object' && value !== null) {
-        const asObj = value;
-        if (seen.has(asObj)) return '[Circular]';
-        seen.add(asObj);
-      }
-      return value;
-    },
-    indent ? 2 : 0
-  );
-};
-
-type FileWriterModule = { FileLogWriter: { write: (line: string) => void } };
-
-let fileWriterPromise: Promise<FileWriterModule> | undefined;
-let fileWriter: FileWriterModule['FileLogWriter'] | undefined;
-
-const getFileWriter = (): void => {
-  if (fileWriter !== undefined) return;
-  if (fileWriterPromise !== undefined) return;
-  fileWriterPromise = import('./FileLogWriter')
-    .then((mod) => {
-      fileWriter = mod.FileLogWriter;
-      return mod;
-    })
-    .catch(() => {
-      fileWriterPromise = undefined;
-      return { FileLogWriter: { write: (_line: string) => undefined } };
-    });
-};
-
-const shouldLogToFile = (): boolean => {
-  // Prefer dynamic lookup so late-bound env (tests, some runtimes) is respected.
-  const channel = Env.get('LOG_CHANNEL', '').trim().toLowerCase();
-  const channelWantsFile = channel === 'file' || channel === 'all';
-  if (!Env.getBool('LOG_TO_FILE', false) && !channelWantsFile) return false;
-  if (typeof process === 'undefined') return false;
-  return true;
-};
-
-const buildFileLine = (params: {
-  formatted: string;
-  data?: unknown;
-  errorMessage?: string;
-}): string => {
-  if (isJsonFormat(getLogFormat())) return params.formatted;
-
-  let line = params.formatted;
-  if (typeof params.errorMessage === 'string' && params.errorMessage.length > 0) {
-    line = `${line} ${params.errorMessage}`;
-  } else if (params.data !== undefined && params.data !== '') {
-    line = `${line} ${safeStringify(redactSensitiveData(params.data))}`;
-  }
-  return line;
-};
-
-const writeToFile = (line: string): void => {
-  if (!shouldLogToFile()) return;
-
-  if (fileWriter !== undefined) {
-    fileWriter.write(line);
-    return;
-  }
-
-  getFileWriter();
-  fileWriterPromise?.then((mod) => mod.FileLogWriter.write(line));
-};
-
-const formatLogMessage = (params: {
-  level: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
-  message: string;
-  data?: unknown;
-  category?: string;
-  errorMessage?: string;
-}): string => {
-  if (isJsonFormat(getLogFormat())) {
-    return safeStringify({
-      timestamp: new Date().toISOString(),
-      level: params.level,
-      message: params.message,
-      category: params.category,
-      data: redactSensitiveData(params.data),
-      error: params.errorMessage,
-    });
-  }
-
-  // text format
-  return `[${params.level.toUpperCase()}] ${params.message}`;
-};
-
-/**
- * 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;
-  }
-
-  if (typeof error === 'string') return error;
-  if (typeof error === 'number' || typeof error === 'bigint') return error.toString();
-  if (typeof error === 'boolean') return error ? 'true' : 'false';
-  if (typeof error === 'symbol') return error.toString();
-  if (typeof error === 'function') return '[Function]';
-
-  try {
-    return safeStringify(error);
-  } catch {
-    return '[Unserializable error]';
-  }
-};
-
-type CloudLogEvent = {
-  timestamp: string;
-  level: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
-  message: string;
-  category?: string;
-  data?: unknown;
-  error?: string;
-};
-
-const emitCloudLogs = (event: CloudLogEvent): void => {
-  // Lazy-load to avoid cycles and avoid cost when disabled.
-  void (async (): Promise<void> => {
-    try {
-      if (event.level === 'error' || event.level === 'fatal') {
-        const mod = await import('./logging/KvLogger');
-        void mod.KvLogger.enqueue(event);
-      }
-    } catch {
-      // best-effort
-    }
-
-    try {
-      if (event.level === 'warn' || event.level === 'error' || event.level === 'fatal') {
-        const mod = await import('./logging/SlackLogger');
-        void mod.SlackLogger.enqueue(event);
-      }
-    } catch {
-      // best-effort
-    }
-
-    try {
-      const mod = await import('./logging/HttpLogger');
-      void mod.HttpLogger.enqueue(event);
-    } catch {
-      // best-effort
-    }
-  })();
-};
-
-// Private helper functions
-const logDebug = (message: string, data?: unknown, category?: string): void => {
-  String(category);
-  if (isDevelopment()) {
-    const timestamp = new Date().toISOString();
-    const out = formatLogMessage({ level: 'debug', message, data, category });
-    writeToFile(buildFileLine({ formatted: out, data }));
-    if (isJsonFormat(getLogFormat())) {
-      console.debug(out); // eslint-disable-line no-console
-      return;
-    }
-    console.debug(out, data ?? ''); // eslint-disable-line no-console
-
-    emitCloudLogs({
-      timestamp,
-      level: 'debug',
-      message,
-      category,
-      data: redactSensitiveData(data),
-    });
-  }
-};
-
-const logInfo = (message: string, data?: unknown, category?: string): void => {
-  String(category);
-  const timestamp = new Date().toISOString();
-  const out = formatLogMessage({ level: 'info', message, data, category });
-  writeToFile(buildFileLine({ formatted: out, data }));
-  if (isJsonFormat(getLogFormat())) {
-    console.log(out); // eslint-disable-line no-console
-  } else {
-    console.log(out, data ?? ''); // eslint-disable-line no-console
-  }
-
-  emitCloudLogs({
-    timestamp,
-    level: 'info',
-    message,
-    category,
-    data: redactSensitiveData(data),
-  });
-};
-
-const logWarn = (message: string, data?: unknown, category?: string): void => {
-  String(category);
-  const timestamp = new Date().toISOString();
-  const out = formatLogMessage({ level: 'warn', message, data, category });
-  writeToFile(buildFileLine({ formatted: out, data }));
-  if (isJsonFormat(getLogFormat())) {
-    console.warn(out); // eslint-disable-line no-console
-  } else {
-    console.warn(out, data ?? ''); // eslint-disable-line no-console
-  }
-
-  emitCloudLogs({
-    timestamp,
-    level: 'warn',
-    message,
-    category,
-    data: redactSensitiveData(data),
-  });
-};
-
-const logError = (message: string, error?: unknown, category?: string): void => {
-  const errorMessage = getErrorMessage(error);
-  String(category);
-  const timestamp = new Date().toISOString();
-  const out = formatLogMessage({
-    level: 'error',
-    message,
-    category,
-    errorMessage,
-  });
-  writeToFile(buildFileLine({ formatted: out, errorMessage }));
-  if (isJsonFormat(getLogFormat())) {
-    console.error(out); // eslint-disable-line no-console
-  } else {
-    console.error(out, errorMessage); // eslint-disable-line no-console
-  }
-
-  emitCloudLogs({
-    timestamp,
-    level: 'error',
-    message,
-    category,
-    error: errorMessage,
-  });
-};
-
-const logFatal = (message: string, error?: unknown, category?: string): void => {
-  const errorMessage = getErrorMessage(error);
-  String(category);
-  const timestamp = new Date().toISOString();
-  const out = formatLogMessage({
-    level: 'fatal',
-    message,
-    category,
-    errorMessage,
-  });
-  writeToFile(buildFileLine({ formatted: out, errorMessage }));
-  if (isJsonFormat(getLogFormat())) {
-    console.error(out); // eslint-disable-line no-console
-  } else {
-    console.error(out, errorMessage); // eslint-disable-line no-console
-  }
-
-  emitCloudLogs({
-    timestamp,
-    level: 'fatal',
-    message,
-    category,
-    error: errorMessage,
-  });
-
-  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);
-    },
-  };
-};
-
-// Expose log cleanup API and sealed namespace with all logger functionality
-export const cleanLogsOnce = async (): Promise<string[]> => {
-  if (!shouldLogToFile()) return [];
-
-  try {
-    const mod = await import('./FileLogWriter');
-    const deleted = mod.cleanOnce();
-    logInfo('Log cleanup executed', { deletedCount: deleted.length });
-    return deleted;
-  } catch (err: unknown) {
-    logError('Log cleanup failed', err as Error);
-    return [];
-  }
-};
-
-export const Logger = Object.freeze({
-  debug: logDebug,
-  info: logInfo,
-  warn: logWarn,
-  error: logError,
-  fatal: logFatal,
-  cleanLogsOnce,
-  scope: createLoggerScope,
-});
+export { Logger } from '@zintrust/core';
 
 export default Logger;

package/src/templates/project/basic/config/logging/HttpLogger.ts.tpl

@@ -10,7 +10,7 @@
  */
 
 import { delay } from '@zintrust/core';
-import { Env } from '../env';
+import { Env } from '@zintrust/core';
 import { ErrorFactory } from '@zintrust/core';
 import { HttpClient } from '@zintrust/core';
 

package/src/templates/project/basic/config/logging/KvLogger.ts.tpl

@@ -8,8 +8,8 @@
  *  - KV_LOG_RETENTION_DAYS (default: 30)
  */
 
-import { Cloudflare } from '../cloudflare';
-import { Env } from '../env';
+import { Cloudflare } from '@zintrust/core';
+import { Env } from '@zintrust/core';
 
 export type KvLogEvent = {
   timestamp: string;

package/src/templates/project/basic/config/logging/SlackLogger.ts.tpl

@@ -9,7 +9,7 @@
  *  - SLACK_LOG_BATCH_WINDOW_MS (default: 5000)
  */
 
-import { Env } from '../env';
+import { Env } from '@zintrust/core';
 import { ErrorFactory } from '@zintrust/core';
 import { HttpClient } from '@zintrust/core';
 

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

@@ -1,123 +1,23 @@
 /**
- * Mail Configuration
- * Runtime mail drivers and settings
- * Sealed namespace for immutability
+ * Mail Configuration (template)
+ *
+ * Keep this file declarative:
+ * - Core owns env parsing/default logic.
+ * - Projects can override values by editing `drivers` and `mailConfigObj`.
  */
 
-import { Env } from './env';
-import type { MailConfigInput, MailDriverConfig } from './type';
-import { ErrorFactory } from '@zintrust/core';
+import { mailConfig as coreMailConfig } from '@zintrust/core';
 
-const isMailDriverConfig = (value: unknown): value is MailDriverConfig => {
-  if (typeof value !== 'object' || value === null) return false;
-  if (!('driver' in value)) return false;
+type MailConfigShape = typeof coreMailConfig;
 
-  const driver = (value as { driver?: unknown }).driver;
-  return typeof driver === 'string' && driver.trim().length > 0;
-};
+export const drivers = {
+  ...coreMailConfig.drivers,
+} satisfies MailConfigShape['drivers'];
 
-const getMailDriver = (config: MailConfigInput, name?: string): MailDriverConfig => {
-  const drivers = config.drivers as Record<string, unknown>;
-  const envSelectedRaw = Env.get('MAIL_CONNECTION', Env.get('MAIL_DRIVER', '')).trim();
-  const selected = (
-    name ??
-    (envSelectedRaw.length > 0 ? envSelectedRaw : undefined) ??
-    config.default
-  )
-    .toString()
-    .trim();
+export const mailConfigObj = {
+  ...coreMailConfig,
+  drivers,
+} satisfies MailConfigShape;
 
-  if (selected.length === 0) {
-    const disabled = drivers['disabled'];
-    if (isMailDriverConfig(disabled)) return disabled;
-    throw ErrorFactory.createConfigError('Mail driver not configured: disabled');
-  }
-
-  if (Object.hasOwn(drivers, selected)) {
-    const resolved = drivers[selected];
-    if (isMailDriverConfig(resolved)) return resolved;
-  }
-
-  throw ErrorFactory.createConfigError(`Mail driver not configured: ${selected}`);
-};
-
-const mailConfigObj = {
-  /**
-   * Default mail driver
-   */
-  default: Env.get('MAIL_CONNECTION', Env.get('MAIL_DRIVER', 'disabled')).trim().toLowerCase(),
-
-  /**
-   * Default "From" identity
-   */
-  from: {
-    address: Env.get('MAIL_FROM_ADDRESS', ''),
-    name: Env.get('MAIL_FROM_NAME', ''),
-  },
-
-  /**
-   * Driver configs
-   */
-  drivers: {
-    disabled: {
-      driver: 'disabled' as const,
-    },
-
-    sendgrid: {
-      driver: 'sendgrid' as const,
-      apiKey: Env.get('SENDGRID_API_KEY', ''),
-    },
-
-    mailgun: {
-      driver: 'mailgun' as const,
-      apiKey: Env.get('MAILGUN_API_KEY', ''),
-      domain: Env.get('MAILGUN_DOMAIN', ''),
-      baseUrl: Env.get('MAILGUN_BASE_URL', 'https://api.mailgun.net').trim(),
-    },
-
-    smtp: {
-      driver: 'smtp' as const,
-      host: Env.get('MAIL_HOST', ''),
-      port: Env.getInt('MAIL_PORT', 587),
-      username: Env.get('MAIL_USERNAME', ''),
-      password: Env.get('MAIL_PASSWORD', ''),
-      secure: (() => {
-        const raw = Env.get('MAIL_SECURE', '').trim().toLowerCase();
-        if (raw === 'starttls') return 'starttls' as const;
-        if (raw === 'tls' || raw === 'ssl' || raw === 'smtps' || raw === 'implicit') return true;
-        if (raw === 'none' || raw === 'off' || raw === 'false' || raw === '0') return false;
-        return Env.getBool('MAIL_SECURE', false);
-      })(),
-    },
-
-    nodemailer: {
-      driver: 'nodemailer' as const,
-      host: Env.get('MAIL_HOST', ''),
-      port: Env.getInt('MAIL_PORT', 587),
-      username: Env.get('MAIL_USERNAME', ''),
-      password: Env.get('MAIL_PASSWORD', ''),
-      secure: (() => {
-        const raw = Env.get('MAIL_SECURE', '').trim().toLowerCase();
-        if (raw === 'starttls') return 'starttls' as const;
-        if (raw === 'tls' || raw === 'ssl' || raw === 'smtps' || raw === 'implicit') return true;
-        if (raw === 'none' || raw === 'off' || raw === 'false' || raw === '0') return false;
-        return Env.getBool('MAIL_SECURE', false);
-      })(),
-    },
-
-    ses: {
-      driver: 'ses' as const,
-      region: Env.get('AWS_REGION', 'us-east-1'),
-    },
-  },
-
-  /**
-   * Get selected driver config
-   */
-  getDriver(name?: string): MailDriverConfig {
-    return getMailDriver(this, name);
-  },
-} as const;
-
-export const mailConfig = Object.freeze(mailConfigObj);
+export const mailConfig = mailConfigObj;
 export type MailConfig = typeof mailConfig;