@zintrust/core 0.1.1 → 0.1.3

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

@@ -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,14 +193,13 @@ 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
-          return Promise.reject(ErrorFactory.createConfigError('Secret rotation not implemented'));
+          throw ErrorFactory.createConfigError('Secret rotation not implemented');
         }
-        return Promise.reject(
-          ErrorFactory.createConfigError('Secret rotation not supported on this platform')
-        );
+        throw ErrorFactory.createConfigError('Secret rotation not supported on this platform');
       },
 
       /**
@@ -191,7 +214,7 @@ const SecretsManagerImpl = {
           case 'deno':
           case 'local':
           default:
-            return Promise.resolve([]);
+            return [];
         }
       },
 
@@ -212,41 +235,39 @@ 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}`);
     throw ErrorFactory.createConfigError('AWS SDK not available in core - use wrapper module');
   } catch (error) {
-    return Promise.reject(
-      ErrorFactory.createTryCatchError(
-        `Failed to retrieve secret from AWS: ${(error as Error).message}`,
-        error
-      )
+    throw ErrorFactory.createTryCatchError(
+      `Failed to retrieve secret from AWS: ${(error as Error).message}`,
+      error
     );
   }
 }
 
+// eslint-disable-next-line @typescript-eslint/require-await
 async function setInAWSSecretsManager(
   key: string,
   _value: string,
   _options?: SetSecretOptions
 ): Promise<void> {
   Logger.info(`[AWS] Setting secret: ${key}`);
-  return Promise.reject(
-    ErrorFactory.createConfigError('AWS SDK not available in core - use wrapper module')
-  );
+  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}`);
-  return Promise.reject(
-    ErrorFactory.createConfigError('AWS SDK not available in core - use wrapper module')
-  );
+  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 Promise.resolve([]);
+  return [];
 }
 
 /**
@@ -294,25 +315,27 @@ 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 } }>
   )['Deno']?.env?.get?.(key);
   if (value === undefined || value === null || value === '') {
-    return Promise.reject(ErrorFactory.createNotFoundError(`Secret not found: ${key}`, { key }));
+    throw ErrorFactory.createNotFoundError(`Secret not found: ${key}`, { key });
   }
-  return Promise.resolve(value);
+  return value;
 }
 
 /**
  * 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 === '') {
-    return Promise.reject(ErrorFactory.createNotFoundError(`Secret not found: ${key}`, { key }));
+    throw ErrorFactory.createNotFoundError(`Secret not found: ${key}`, { key });
   }
-  return Promise.resolve(value);
+  return 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;