@zintrust/core 0.1.0 → 0.1.2

package/src/templates/project/basic/app/Toolkit/Notification/sendSms.ts.tpl

@@ -0,0 +1,13 @@
+import { sendSms } from '@notification/drivers/Twilio';
+
+export async function sendSmsNotification(
+  accountSid: string,
+  authToken: string,
+  from: string,
+  to: string,
+  body: string
+): Promise<void> {
+  await sendSms({ accountSid, authToken, from }, { to, body });
+}
+
+export default Object.freeze({ sendSmsNotification });

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

@@ -0,0 +1,240 @@
+/**
+ * FileLogWriter (Node.js only)
+ *
+ * Provides best-effort file logging with daily + size-based rotation.
+ * This module imports Node built-ins and should be loaded only in Node environments.
+ */
+
+import { ensureDirSafe } from '@common/index';
+import { Env } from '@config/env';
+import * as fs from '@node-singletons/fs';
+import * as path from '@node-singletons/path';
+
+const getCwdSafe = (): string => {
+  try {
+    if (typeof process === 'undefined' || typeof process.cwd !== 'function') return '';
+    return process.cwd();
+  } catch {
+    return '';
+  }
+};
+
+const getDateStr = (d: Date): string => d.toISOString().slice(0, 10);
+
+const isAppLogFile = (fileName: string): boolean =>
+  fileName.startsWith('app-') && fileName.endsWith('.log');
+
+const parseDateFromLogFilename = (fileName: string): number | null => {
+  const match = /^app-(\d{4}-\d{2}-\d{2})(?:-\d+)?\.log$/.exec(fileName);
+  if (match?.[1] === undefined) return null;
+
+  const parsed = Date.parse(`${match[1]}T00:00:00.000Z`);
+  return Number.isNaN(parsed) ? null : parsed;
+};
+
+const isOlderThanCutoffByMtime = (fullPath: string, cutoff: number): boolean => {
+  try {
+    const stat = fs.statSync(fullPath);
+    return stat.mtime.getTime() < cutoff;
+  } catch {
+    return false;
+  }
+};
+
+const safeUnlink = (fullPath: string): void => {
+  try {
+    fs.unlinkSync(fullPath);
+  } catch {
+    // best-effort
+  }
+};
+
+const readDirSafe = (dirPath: string): string[] => {
+  try {
+    return fs.readdirSync(dirPath);
+  } catch {
+    return [];
+  }
+};
+
+const shouldDeleteLogFile = (fileName: string, fullPath: string, cutoff: number): boolean => {
+  const parsed = parseDateFromLogFilename(fileName);
+  if (parsed !== null) return parsed < cutoff;
+
+  return isOlderThanCutoffByMtime(fullPath, cutoff);
+};
+
+const cleanupOldLogs = (logsDir: string, keepDays: number): void => {
+  if (keepDays <= 0) return;
+
+  const cutoff = Date.now() - keepDays * 24 * 60 * 60 * 1000;
+  const files = readDirSafe(logsDir);
+  if (files.length === 0) return;
+
+  for (const fileName of files) {
+    if (!isAppLogFile(fileName)) continue;
+
+    const fullPath = path.join(logsDir, fileName);
+    if (!shouldDeleteLogFile(fileName, fullPath, cutoff)) continue;
+
+    safeUnlink(fullPath);
+  }
+};
+
+type CleanOnceOptions = {
+  logsDir?: string;
+  keepDays?: number;
+  maxTotalSize?: number;
+  keepFiles?: number;
+};
+
+const listAppLogFiles = (
+  logsDir: string,
+  order: 'newest-first' | 'oldest-first'
+): Array<{ name: string; path: string }> => {
+  const files = readDirSafe(logsDir)
+    .filter((f) => isAppLogFile(f))
+    .map((f) => ({ name: f, path: path.join(logsDir, f) }));
+
+  return files.sort((a, b) => {
+    if (a.name === b.name) return 0;
+    const newerFirst = a.name < b.name ? 1 : -1;
+    return order === 'newest-first' ? newerFirst : -newerFirst;
+  });
+};
+
+const enforceKeepFilesPolicy = (
+  filesNewestFirst: Array<{ name: string; path: string }>,
+  keepFiles: number | undefined,
+  deleted: string[]
+): void => {
+  if (typeof keepFiles !== 'number' || keepFiles < 0) return;
+  if (filesNewestFirst.length <= keepFiles) return;
+
+  const toDelete = filesNewestFirst.slice(keepFiles);
+  for (const f of toDelete) {
+    safeUnlink(f.path);
+    deleted.push(f.path);
+  }
+};
+
+const getFileSizesTotal = (
+  filesOldestFirst: Array<{ name: string; path: string }>
+): { total: number; sizes: Array<{ path: string; size: number }> } => {
+  let total = 0;
+  const sizes: Array<{ path: string; size: number }> = [];
+
+  for (const file of filesOldestFirst) {
+    try {
+      const stat = fs.statSync(file.path);
+      sizes.push({ path: file.path, size: stat.size });
+      total += stat.size;
+    } catch {
+      // ignore
+    }
+  }
+
+  return { total, sizes };
+};
+
+const deleteOldestUntilWithinLimit = (
+  sizesOldestFirst: Array<{ path: string; size: number }>,
+  maxTotalSize: number,
+  deleted: string[],
+  initialTotal: number
+): void => {
+  let total = initialTotal;
+
+  let idx = 0;
+  while (total > maxTotalSize && idx < sizesOldestFirst.length) {
+    const del = sizesOldestFirst[idx];
+    safeUnlink(del.path);
+    deleted.push(del.path);
+    total -= del.size;
+    idx++;
+  }
+};
+
+const enforceMaxTotalSizePolicy = (
+  logsDir: string,
+  maxTotalSize: number | undefined,
+  deleted: string[]
+): void => {
+  if (typeof maxTotalSize !== 'number' || maxTotalSize <= 0) return;
+
+  const remainingOldestFirst = listAppLogFiles(logsDir, 'oldest-first');
+  const { total, sizes } = getFileSizesTotal(remainingOldestFirst);
+  deleteOldestUntilWithinLimit(sizes, maxTotalSize, deleted, total);
+};
+
+/**
+ * Clean log files with additional retention policies.
+ * Returns an array of deleted file paths for auditing/tests.
+ */
+export const cleanOnce = (options?: CleanOnceOptions): string[] => {
+  const cwd = getCwdSafe();
+  if (cwd === '') return [];
+
+  const logsDir = options?.logsDir ?? path.join(cwd, 'logs');
+  const keepDays = options?.keepDays ?? Env.LOG_ROTATION_DAYS;
+  const maxTotalSize = options?.maxTotalSize ?? Env.getInt('LOG_MAX_TOTAL_SIZE', 0);
+  const keepFiles = options?.keepFiles ?? Env.getInt('LOG_KEEP_FILES', 0);
+
+  // Step 1: delete by age
+  cleanupOldLogs(logsDir, keepDays);
+
+  const deleted: string[] = [];
+
+  // Step 2: enforce keepFiles (keep newest N files)
+  const filesNewestFirst = listAppLogFiles(logsDir, 'newest-first');
+  enforceKeepFilesPolicy(filesNewestFirst, keepFiles, deleted);
+
+  // Step 3: enforce max total size
+  enforceMaxTotalSizePolicy(logsDir, maxTotalSize, deleted);
+
+  return deleted;
+};
+
+const rotateIfNeeded = (logFile: string, maxSizeBytes: number): void => {
+  if (maxSizeBytes <= 0) return;
+
+  try {
+    if (!fs.existsSync(logFile)) return;
+
+    const stat = fs.statSync(logFile);
+    if (stat.size <= maxSizeBytes) return;
+
+    const ext = '.log';
+    const base = logFile.endsWith(ext) ? logFile.slice(0, -ext.length) : logFile;
+    const rotated = `${base}-${Date.now()}${ext}`;
+    fs.renameSync(logFile, rotated);
+  } catch {
+    // best-effort
+  }
+};
+
+export const FileLogWriter = Object.freeze({
+  write(line: string): void {
+    const cwd = getCwdSafe();
+    if (cwd === '') return;
+
+    const logsDir = path.join(cwd, 'logs');
+    ensureDirSafe(logsDir);
+
+    const dateStr = getDateStr(new Date());
+    const logFile = path.join(logsDir, `app-${dateStr}.log`);
+
+    rotateIfNeeded(logFile, Env.LOG_ROTATION_SIZE);
+
+    try {
+      fs.appendFileSync(logFile, `${line}\n`);
+    } catch {
+      // best-effort
+      return;
+    }
+
+    cleanupOldLogs(logsDir, Env.LOG_ROTATION_DAYS);
+  },
+});
+
+export default FileLogWriter;

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

@@ -5,7 +5,7 @@
  */
 
 import { Logger } from '@config/logger';
-import { ErrorFactory } from '@zintrust/core';
+import { ErrorFactory } from '@exceptions/ZintrustError';
 
 export interface CloudflareKV {
   get(key: string): Promise<string | null>;
@@ -38,6 +38,25 @@ interface SecretsManagerInstance {
   clearCache(key?: string): void;
 }
 
+function pruneCache(
+  cache: Map<string, { value: string; expiresAt: number }>,
+  maxEntries: number
+): void {
+  if (cache.size <= maxEntries) return;
+
+  const now = Date.now();
+  for (const [key, entry] of cache.entries()) {
+    if (entry.expiresAt <= now) cache.delete(key);
+  }
+
+  // If still large, drop oldest entries (Map preserves insertion order)
+  while (cache.size > maxEntries) {
+    const next = cache.keys().next();
+    if (next.done === true) break;
+    cache.delete(next.value);
+  }
+}
+
 /**
  * Get secret value from appropriate backend
  */
@@ -53,6 +72,9 @@ async function runGetSecret(
     return cached.value;
   }
 
+  // Opportunistic cleanup if cache has grown
+  pruneCache(cache, 500);
+
   let value: string;
 
   switch (config.platform) {
@@ -77,6 +99,8 @@ async function runGetSecret(
     expiresAt: Date.now() + ttl,
   });
 
+  pruneCache(cache, 500);
+
   return value;
 }
 
@@ -169,6 +193,7 @@ const SecretsManagerImpl = {
       /**
        * Rotate secret (trigger new secret generation)
        */
+      // eslint-disable-next-line @typescript-eslint/require-await
       async rotateSecret(_key: string): Promise<void> {
         if (config.platform === 'aws') {
           // AWS Secrets Manager supports automatic rotation
@@ -210,6 +235,7 @@ const SecretsManagerImpl = {
 /**
  * AWS Secrets Manager integration
  */
+// eslint-disable-next-line @typescript-eslint/require-await
 async function getFromAWSSecretsManager(key: string): Promise<string> {
   try {
     Logger.debug(`[AWS] Getting secret: ${key}`);
@@ -222,6 +248,7 @@ async function getFromAWSSecretsManager(key: string): Promise<string> {
   }
 }
 
+// eslint-disable-next-line @typescript-eslint/require-await
 async function setInAWSSecretsManager(
   key: string,
   _value: string,
@@ -231,11 +258,13 @@ async function setInAWSSecretsManager(
   throw ErrorFactory.createConfigError('AWS SDK not available in core - use wrapper module');
 }
 
+// eslint-disable-next-line @typescript-eslint/require-await
 async function deleteFromAWSSecretsManager(key: string): Promise<void> {
   Logger.info(`[AWS] Deleting secret: ${key}`);
   throw ErrorFactory.createConfigError('AWS SDK not available in core - use wrapper module');
 }
 
+// eslint-disable-next-line @typescript-eslint/require-await
 async function listFromAWSSecretsManager(pattern?: string): Promise<string[]> {
   Logger.info(`[AWS] Listing secrets with pattern: ${pattern ?? '*'}`);
   return [];
@@ -286,6 +315,7 @@ async function listFromCloudflareKV(config: SecretConfig, pattern?: string): Pro
 /**
  * Deno environment integration
  */
+// eslint-disable-next-line @typescript-eslint/require-await
 async function getFromDenoEnv(key: string): Promise<string> {
   const value = (
     globalThis as unknown as Record<string, { env?: { get?: (key: string) => string } }>
@@ -299,6 +329,7 @@ async function getFromDenoEnv(key: string): Promise<string> {
 /**
  * Local environment variables (Node.js)
  */
+// eslint-disable-next-line @typescript-eslint/require-await
 async function getFromEnv(key: string): Promise<string> {
   const value = process.env[key];
   if (value === undefined || value === null || value === '') {

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

@@ -0,0 +1,151 @@
+import { appConfig } from '@config/app';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+export type StartupConfigValidationError = {
+  key: string;
+  value: unknown;
+  message: string;
+};
+
+export type StartupConfigValidationResult = {
+  valid: boolean;
+  errors: StartupConfigValidationError[];
+};
+
+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 getEnvInt = (key: string, defaultValue: number): number => {
+  const raw = getEnvString(key, String(defaultValue));
+  return Number.parseInt(raw, 10);
+};
+
+export const StartupConfigValidator = Object.freeze({
+  validate(): StartupConfigValidationResult {
+    const errors: StartupConfigValidationError[] = [];
+
+    const nodeEnv = getEnvString('NODE_ENV', 'development');
+    validateEnum(errors, 'NODE_ENV', nodeEnv, ['development', 'production', 'testing', 'test']);
+
+    const appPort = getEnvInt('APP_PORT', 3000);
+    validateIntRange(errors, 'APP_PORT', appPort, 1, 65535);
+
+    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']);
+
+    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);
+
+    if (appConfig.isProduction()) {
+      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'
+        );
+      }
+    }
+
+    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;

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

@@ -6,6 +6,47 @@
 
 import { Env } from '@config/env';
 
+type ProcessLike = { env?: Record<string, string | undefined> };
+
+type Environment = 'development' | 'dev' | 'production' | 'prod' | 'pro' | 'testing' | 'test';
+type StartMode = 'development' | 'production' | 'testing';
+
+const getProcessLike = (): ProcessLike | undefined => {
+  return typeof process === 'undefined' ? undefined : (process as unknown as ProcessLike);
+};
+
+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);
+  }
+
+  const proc = getProcessLike();
+  const raw = proc?.env?.[key];
+  return raw ?? defaultValue;
+};
+
+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;
 
@@ -13,39 +54,64 @@ const getSafeEnv = (): NodeJS.ProcessEnv => {
     ...(baseEnv as NodeJS.ProcessEnv),
 
     // Ensure required keys exist (env.d.ts augments ProcessEnv with required fields)
-    NODE_ENV: baseEnv.NODE_ENV ?? (Env.NODE_ENV as NodeJS.ProcessEnv['NODE_ENV']),
-    USE_RAW_QRY: baseEnv.USE_RAW_QRY ?? (Env.get('USE_RAW_QRY') || undefined),
-    SERVICE_API_KEY: baseEnv.SERVICE_API_KEY ?? Env.get('SERVICE_API_KEY', ''),
-    SERVICE_JWT_SECRET: baseEnv.SERVICE_JWT_SECRET ?? Env.get('SERVICE_JWT_SECRET', ''),
-    BASE_URL: baseEnv.BASE_URL ?? Env.get('BASE_URL', ''),
-    MODE: baseEnv.MODE ?? Env.get('MODE', ''),
+    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: Env.SAFE_PATH,
+    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: Env.APP_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: Env.NODE_ENV as 'development' | 'production' | 'testing',
+  environment: normalizeMode(),
 
   /**
    * Application port
    */
-  port: Env.PORT,
+  port:
+    typeof (Env as unknown as { PORT?: unknown }).PORT === 'number'
+      ? (Env as unknown as { PORT: number }).PORT
+      : readEnvInt('APP_PORT', 3000),
 
   /**
    * Application host
    */
-  host: Env.HOST,
+  host:
+    typeof (Env as unknown as { HOST?: unknown }).HOST === 'string'
+      ? (Env as unknown as { HOST: string }).HOST
+      : readEnvString('HOST', 'localhost'),
 
   /**
    * Is development environment
@@ -71,22 +137,25 @@ const appConfigObj = {
   /**
    * Application debug mode
    */
-  debug: Env.DEBUG,
+  debug:
+    typeof (Env as unknown as { DEBUG?: unknown }).DEBUG === 'boolean'
+      ? (Env as unknown as { DEBUG: boolean }).DEBUG
+      : readEnvBool('DEBUG', false),
 
   /**
    * Application timezone
    */
-  timezone: Env.get('APP_TIMEZONE', 'UTC'),
+  timezone: readEnvString('APP_TIMEZONE', 'UTC'),
 
   /**
    * Request timeout (milliseconds)
    */
-  requestTimeout: Env.getInt('REQUEST_TIMEOUT', 30000),
+  requestTimeout: readEnvInt('REQUEST_TIMEOUT', 30000),
 
   /**
    * Max request body size
    */
-  maxBodySize: Env.get('MAX_BODY_SIZE', '10mb'),
+  maxBodySize: readEnvString('MAX_BODY_SIZE', '10mb'),
 
   getSafeEnv,
 } as const;