@zintrust/core 0.1.27 → 0.1.28

package/src/scheduler/ScheduleRunner.ts

@@ -0,0 +1,219 @@
+/**
+ * ScheduleRunner
+ * Lightweight, zero-dependency schedule runner for long-running runtimes
+ */
+
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import type { ISchedule, IScheduleKernel } from '@scheduler/types';
+
+type InternalScheduleState = {
+  schedule: ISchedule;
+  intervalId?: ReturnType<typeof globalThis.setInterval>;
+  isRunning: boolean;
+  runningPromise?: Promise<void>;
+  lastRunAt?: number;
+};
+
+type RunnerState = {
+  schedules: Map<string, InternalScheduleState>;
+  started: boolean;
+  kernel?: IScheduleKernel;
+};
+
+type ScheduleRunner = {
+  register: (schedule: ISchedule) => void;
+  start: (kernel?: IScheduleKernel) => void;
+  stop: (timeoutMs?: number) => Promise<void>;
+  list: () => ISchedule[];
+  runOnce: (name: string, kernel?: IScheduleKernel) => Promise<void>;
+};
+
+const createRegister =
+  (
+    runner: RunnerState,
+    invokeHandler: (state: InternalScheduleState, kernel?: IScheduleKernel) => Promise<void>
+  ) =>
+  (schedule: ISchedule): void => {
+    if (runner.schedules.has(schedule.name)) {
+      Logger.warn(`Schedule replaced: ${schedule.name}`);
+    }
+
+    const state: InternalScheduleState = {
+      schedule,
+      isRunning: false,
+    };
+
+    runner.schedules.set(schedule.name, state);
+
+    // If schedules are already started, register should take effect immediately.
+    if (runner.started && schedule.enabled !== false) {
+      if (schedule.runOnStart === true) {
+        void invokeHandler(state, runner.kernel);
+      }
+
+      if (typeof schedule.intervalMs === 'number' && schedule.intervalMs > 0) {
+        state.intervalId = globalThis.setInterval(() => {
+          void invokeHandler(state, runner.kernel);
+        }, schedule.intervalMs);
+      }
+    }
+  };
+
+const createInvokeHandler =
+  () =>
+  async (state: InternalScheduleState, kernel?: IScheduleKernel): Promise<void> => {
+    if (state.isRunning) {
+      Logger.info(`Skipping overlapping run for schedule: ${state.schedule.name}`);
+      return;
+    }
+
+    state.isRunning = true;
+
+    try {
+      const handlerPromise = Promise.resolve()
+        .then(async () => state.schedule.handler(kernel))
+        .then(() => {
+          state.lastRunAt = Date.now();
+        })
+        .catch((error: unknown) => {
+          Logger.error(`Schedule '${state.schedule.name}' failed:`, error as Error);
+        })
+        .then(() => undefined);
+
+      state.runningPromise = handlerPromise;
+      await handlerPromise;
+    } finally {
+      state.isRunning = false;
+      state.runningPromise = undefined;
+    }
+  };
+
+const createStart =
+  (
+    runner: RunnerState,
+    invokeHandler: (state: InternalScheduleState, kernel?: IScheduleKernel) => Promise<void>
+  ) =>
+  (kernel?: IScheduleKernel): void => {
+    if (runner.started) return;
+    runner.started = true;
+    runner.kernel = kernel;
+
+    for (const [, state] of runner.schedules) {
+      const { schedule } = state;
+      if (schedule.enabled === false) continue;
+
+      if (schedule.runOnStart === true) {
+        // fire-and-forget (handled by invokeHandler which logs errors)
+        void invokeHandler(state, kernel);
+      }
+
+      if (typeof schedule.intervalMs === 'number' && schedule.intervalMs > 0) {
+        const id = globalThis.setInterval(() => {
+          // fire and forget invocation; overlapping runs are protected inside
+          void invokeHandler(state, kernel);
+        }, schedule.intervalMs);
+
+        state.intervalId = id;
+      }
+    }
+  };
+
+const createStop = (runner: RunnerState) => async (): Promise<void> => {
+  if (!runner.started) return;
+  runner.started = false;
+  runner.kernel = undefined;
+
+  // Clear intervals
+  for (const [, state] of runner.schedules) {
+    if (state.intervalId !== undefined) {
+      globalThis.clearInterval(state.intervalId);
+      state.intervalId = undefined;
+    }
+  }
+
+  // Await running handlers (runningPromise is guaranteed not to reject)
+  const running: Promise<void>[] = [];
+  for (const [, state] of runner.schedules) {
+    if (state.isRunning && state.runningPromise !== undefined) {
+      running.push(state.runningPromise);
+    }
+  }
+
+  if (running.length > 0) {
+    await Promise.all(running);
+  }
+};
+
+const withTimeout = async (promise: Promise<void>, timeoutMs?: number): Promise<void> => {
+  const ms = typeof timeoutMs === 'number' ? timeoutMs : 0;
+  if (ms <= 0) {
+    await promise;
+    return;
+  }
+
+  let timeoutId: ReturnType<typeof globalThis.setTimeout> | undefined;
+  try {
+    await Promise.race([
+      promise,
+      new Promise<void>((resolve) => {
+        timeoutId = globalThis.setTimeout(() => {
+          Logger.error('ScheduleRunner.stop() timed out; continuing shutdown', {
+            timeoutMs: ms,
+          });
+          resolve();
+        }, ms);
+      }),
+    ]);
+  } finally {
+    if (timeoutId !== undefined) globalThis.clearTimeout(timeoutId);
+  }
+};
+
+const createStopWithTimeout =
+  (stop: () => Promise<void>) =>
+  async (timeoutMs?: number): Promise<void> => {
+    await withTimeout(stop(), timeoutMs);
+  };
+
+const createList = (runner: RunnerState) => (): ISchedule[] =>
+  Array.from(runner.schedules.values()).map((s) => s.schedule);
+
+const createRunOnce =
+  (
+    runner: RunnerState,
+    invokeHandler: (state: InternalScheduleState, kernel?: IScheduleKernel) => Promise<void>
+  ) =>
+  async (name: string, kernel?: IScheduleKernel): Promise<void> => {
+    const state = runner.schedules.get(name);
+    if (state === undefined) throw ErrorFactory.createNotFoundError(`Schedule not found: ${name}`);
+    if (state.schedule.enabled === false) return;
+    await invokeHandler(state, kernel ?? runner.kernel);
+  };
+
+export const create = (): Readonly<ScheduleRunner> => {
+  const runner: RunnerState = {
+    schedules: new Map<string, InternalScheduleState>(),
+    started: false,
+    kernel: undefined,
+  };
+
+  const invokeHandler = createInvokeHandler();
+
+  const register = createRegister(runner, invokeHandler);
+  const start = createStart(runner, invokeHandler);
+  const stopRaw = createStop(runner);
+  const stop = createStopWithTimeout(stopRaw);
+  const list = createList(runner);
+  const runOnce = createRunOnce(runner, invokeHandler);
+
+  return Object.freeze({
+    register,
+    start,
+    stop,
+    list,
+    runOnce,
+  });
+};
+
+export default { create };

package/src/scheduler/index.ts

@@ -0,0 +1,2 @@
+export { create as createScheduleRunner } from '@scheduler/ScheduleRunner';
+export type { ISchedule } from '@scheduler/types';

package/src/scheduler/types.ts

@@ -0,0 +1,18 @@
+/**
+ * Scheduler types
+ */
+
+export type IScheduleKernel = Readonly<{
+  getContainer?: () => unknown;
+  getRouter?: () => unknown;
+}>;
+
+export type IScheduleHandler = (kernel?: IScheduleKernel) => Promise<void> | void;
+
+export type ISchedule = {
+  name: string;
+  intervalMs?: number; // interval in milliseconds; if absent, schedule won't be auto-registered for intervals
+  handler: IScheduleHandler;
+  enabled?: boolean;
+  runOnStart?: boolean;
+};

package/src/schedules/index.ts

@@ -0,0 +1 @@
+export { default as logCleanup } from '@schedules/log-cleanup';

package/src/schedules/log-cleanup.ts

@@ -0,0 +1,21 @@
+import { Env } from '@config/env';
+import { Logger, cleanLogsOnce } from '@config/logger';
+import type { ISchedule } from '@scheduler/types';
+
+const intervalMs = Env.getInt('LOG_CLEANUP_INTERVAL_MS', 3600000);
+
+const LogCleanupSchedule: ISchedule = {
+  name: 'log.cleanup',
+  intervalMs: intervalMs,
+  handler: async () => {
+    try {
+      await cleanLogsOnce();
+    } catch (err) {
+      Logger.error('Log cleanup schedule failed', err as Error);
+    }
+  },
+  enabled: Env.getBool('LOG_CLEANUP_ENABLED', Env.getBool('LOG_TO_FILE', false)),
+  runOnStart: false,
+};
+
+export default LogCleanupSchedule;

package/src/scripts/GenerateEnvArtifacts.ts

@@ -0,0 +1,203 @@
+/**
+ * GenerateEnvArtifacts
+ * - Generates env.d.ts and .env.example from the framework's Env usage.
+ *
+ * Goals:
+ * - Developer convenience (discoverable env keys)
+ * - Keep env.d.ts + .env.example in sync with src/config usage
+ *
+ * Usage:
+ *   tsx src/scripts/GenerateEnvArtifacts.ts
+ */
+
+import { Logger } from '@config/logger';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import fs from '@node-singletons/fs';
+import * as path from '@node-singletons/path';
+
+type EnvUsage = {
+  key: string;
+  defaultValue?: string;
+};
+
+const ROOT_DIR = path.resolve(process.cwd());
+const GENERATED_MARKER = 'Generated by src/scripts/GenerateEnvArtifacts.ts';
+
+const walkDir = (dirAbs: string): string[] => {
+  const out: string[] = [];
+  const entries = fs.readdirSync(dirAbs, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === 'coverage')
+      continue;
+    const abs = path.join(dirAbs, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...walkDir(abs));
+      continue;
+    }
+    if (entry.isFile() && entry.name.endsWith('.ts')) out.push(abs);
+  }
+  return out;
+};
+
+const readText = (fileAbs: string): string => fs.readFileSync(fileAbs, 'utf8');
+
+const uniq = <T>(arr: T[]): T[] => Array.from(new Set(arr));
+
+const parseEnvUsages = (content: string): EnvUsage[] => {
+  const out: EnvUsage[] = [];
+
+  // Avoid catastrophic backtracking by not using complex regexes to parse arbitrary JS.
+  // Instead scan for Env.<method>(...), handle quotes/escapes and balanced parentheses in linear time.
+  const extractArgs = (parenIdx: number): { args: string; endIdx: number } => {
+    let i = parenIdx;
+    if (content[i] !== '(') return { args: '', endIdx: i + 1 };
+    i++; // move past '('
+    const start = i;
+    let depth = 1;
+
+    // Skip a quoted string starting at idx (idx points at the opening quote).
+    const skipQuoted = (idx: number): number => {
+      let newIdx = idx;
+      const quote = content[newIdx];
+      newIdx++;
+      while (newIdx < content.length) {
+        if (content[newIdx] === '\\') {
+          newIdx += 2;
+          continue;
+        }
+        if (content[newIdx] === quote) {
+          return newIdx + 1;
+        }
+        newIdx++;
+      }
+      return newIdx;
+    };
+
+    while (i < content.length && depth > 0) {
+      const ch = content[i];
+
+      if (ch === "'" || ch === '"') {
+        i = skipQuoted(i);
+        continue;
+      }
+
+      if (ch === '(') {
+        depth++;
+        i++;
+        continue;
+      }
+
+      if (ch === ')') {
+        depth--;
+        if (depth === 0) {
+          return { args: content.slice(start, i), endIdx: i + 1 };
+        }
+        i++;
+        continue;
+      }
+
+      i++;
+    }
+
+    // unbalanced or EOF: return what we have
+    return { args: content.slice(start, i), endIdx: i };
+  };
+
+  const methods = ['get', 'getInt', 'getBool'];
+  for (const method of methods) {
+    const token = `Env.${method}(`;
+    let idx = content.indexOf(token, 0);
+
+    while (idx !== -1) {
+      const parenIdx = idx + token.length - 1; // position of '('
+      const { args, endIdx } = extractArgs(parenIdx);
+
+      // args looks like: ['KEY'[, defaultVal]]
+      const keyMatch = /^\s*['"]([A-Z0-9_]+)['"]/.exec(args);
+      if (keyMatch) {
+        const key = keyMatch[1];
+        const rest = args.slice(keyMatch[0].length);
+        const restTrimmed = rest.replace(/^\s*,\s*/, '').trim();
+        const defaultValue = restTrimmed.length > 0 ? restTrimmed : undefined;
+        out.push({ key, defaultValue });
+      }
+
+      idx = content.indexOf(token, endIdx);
+    }
+  }
+
+  return out;
+};
+
+const renderEnvDts = (keys: string[]): string => {
+  const sortedKeys = keys.toSorted((a, b) => a.localeCompare(b));
+  const lines = sortedKeys.map((k) => `    ${k}?: string | undefined;`).join('\n');
+
+  return `declare namespace NodeJS {\n  interface ProcessEnv {\n    NODE_ENV: 'development' | 'production' | 'testing' | undefined;\n\n${lines}\n  }\n}\n`;
+};
+
+const renderEnvExample = (keys: string[]): string => {
+  const header = `# ZinTrust Framework - Environment Configuration\n# Generated by src/scripts/GenerateEnvArtifacts.ts\n# Copy this file to .env and configure for your environment\n\n`;
+  const sortedKeys = keys.toSorted((a, b) => a.localeCompare(b));
+  const body = sortedKeys
+    .filter((k) => k !== 'NODE_ENV')
+    .map((k) => `${k}=`)
+    .join('\n');
+  return header + `NODE_ENV=development\n` + body + `\n`;
+};
+
+const renderEnvKeys = (keys: string[]): string => {
+  const sortedKeys = keys.toSorted((a, b) => a.localeCompare(b));
+  return sortedKeys.join('\n') + '\n';
+};
+
+const writeIfChanged = (fileAbs: string, next: string): void => {
+  const prev = fs.existsSync(fileAbs) ? fs.readFileSync(fileAbs, 'utf8') : '';
+  if (prev === next) return;
+  fs.writeFileSync(fileAbs, next, 'utf8');
+};
+
+const shouldOverwriteEnvExample = (envExampleAbs: string): boolean => {
+  if (!fs.existsSync(envExampleAbs)) return true;
+  const prev = fs.readFileSync(envExampleAbs, 'utf8');
+  return prev.includes(GENERATED_MARKER);
+};
+
+const main = (): void => {
+  try {
+    const configDir = path.join(ROOT_DIR, 'src', 'config');
+    const configFiles = walkDir(configDir);
+
+    const usages = configFiles.flatMap((f) => parseEnvUsages(readText(f)));
+    const keys = uniq(usages.map((u) => u.key));
+
+    if (keys.length === 0) {
+      throw ErrorFactory.createTryCatchError('No Env.get usages found under src/config');
+    }
+
+    // env.d.ts
+    const envDtsPath = path.join(ROOT_DIR, 'env.d.ts');
+    writeIfChanged(envDtsPath, renderEnvDts(keys));
+
+    // .env.example (non-destructive by default)
+    const envExamplePath = path.join(ROOT_DIR, '.env.example');
+    const generatedExamplePath = path.join(ROOT_DIR, '.env.example.generated');
+    const renderedExample = renderEnvExample(keys);
+    if (shouldOverwriteEnvExample(envExamplePath)) {
+      writeIfChanged(envExamplePath, renderedExample);
+    } else {
+      writeIfChanged(generatedExamplePath, renderedExample);
+    }
+
+    // .env.keys (for quick discovery / tooling)
+    const envKeysPath = path.join(ROOT_DIR, '.env.keys');
+    writeIfChanged(envKeysPath, renderEnvKeys(keys));
+
+    Logger.info(`✓ Generated env artifacts (keys: ${keys.length})`);
+  } catch (error) {
+    Logger.error('GenerateEnvArtifacts failed', error);
+    process.exit(1);
+  }
+};
+
+main();

package/src/scripts/TemplateImportsCheck.ts

@@ -0,0 +1,180 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import ts from 'typescript';
+
+const TEMPLATES_ROOT = path.resolve(process.cwd(), 'src/templates');
+
+const bannedPrefixes = [
+  '@exceptions/',
+  '@orm/',
+  '@routing/',
+  '@middleware/',
+  '@boot/',
+  '@container/',
+  '@http/',
+  '@httpClient/',
+  '@security/',
+  '@validation/',
+  '@profiling/',
+  '@tools/',
+  '@cache/',
+  '@mail/',
+  '@storage/',
+  '@node-singletons/',
+  '@common/',
+  '@/',
+  './',
+  '../',
+];
+
+function listFilesRecursive(root: string): string[] {
+  const out: string[] = [];
+  const entries = fs.readdirSync(root, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...listFilesRecursive(full));
+    } else {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function isTemplateFile(filePath: string): boolean {
+  return filePath.endsWith('.tpl');
+}
+
+function checkFile(filePath: string): Array<{ line: number; spec: string; text: string }> {
+  const text = fs.readFileSync(filePath, 'utf8');
+  const lines = text.split(/\r?\n/);
+
+  const offenses: Array<{ line: number; spec: string; text: string }> = [];
+
+  const addIfBanned = (lineNo: number, spec: string, lineText: string): void => {
+    const trimmed = spec.trim();
+    if (
+      trimmed === '@zintrust/core' ||
+      trimmed === '@zintrust/core/node' ||
+      trimmed === '@zintrust/core/start'
+    ) {
+      return;
+    }
+    if (trimmed.startsWith('node:')) return;
+
+    for (const prefix of bannedPrefixes) {
+      if (trimmed.startsWith(prefix)) {
+        offenses.push({ line: lineNo, spec: trimmed, text: lineText });
+        return;
+      }
+    }
+  };
+
+  const importFromRe = /\bfrom\s+['"]([^'"]+)['"]/g;
+  const dynamicImportRe = /\bimport\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+  for (let i = 0; i < lines.length; i++) {
+    const lineText = lines[i] ?? '';
+
+    // from '...'
+    for (const m of lineText.matchAll(importFromRe)) {
+      const spec = m[1];
+      if (typeof spec === 'string') addIfBanned(i + 1, spec, lineText);
+    }
+
+    // import('...')
+    for (const m of lineText.matchAll(dynamicImportRe)) {
+      const spec = m[1];
+      if (typeof spec === 'string') addIfBanned(i + 1, spec, lineText);
+    }
+  }
+
+  return offenses;
+}
+
+function looksLikeTypeScriptTemplate(text: string): boolean {
+  // Only attempt TS parsing when the template appears to contain TS module syntax.
+  // Many templates are not TS (markdown/env/etc.) and should not be validated this way.
+  return /\b(import|export)\b/.test(text);
+}
+
+function getTypeScriptSyntaxErrors(filePath: string): Array<{ line: number; message: string }> {
+  const text = fs.readFileSync(filePath, 'utf8');
+  if (!looksLikeTypeScriptTemplate(text)) return [];
+
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    text,
+    ts.ScriptTarget.ESNext,
+    true,
+    ts.ScriptKind.TS
+  );
+  const diagnostics = (sourceFile as ts.SourceFile & { parseDiagnostics?: ts.Diagnostic[] })
+    .parseDiagnostics;
+  if (!diagnostics || diagnostics.length === 0) return [];
+
+  const out: Array<{ line: number; message: string }> = [];
+  for (const d of diagnostics) {
+    const message = ts.flattenDiagnosticMessageText(d.messageText, '\n');
+    const pos = typeof d.start === 'number' ? d.start : 0;
+    const { line } = sourceFile.getLineAndCharacterOfPosition(pos);
+    out.push({ line: line + 1, message });
+  }
+  return out;
+}
+
+function main(): void {
+  if (!fs.existsSync(TEMPLATES_ROOT)) {
+    process.stderr.write(`Templates root not found: ${TEMPLATES_ROOT}\n`);
+    process.exit(1);
+  }
+
+  const files = listFilesRecursive(TEMPLATES_ROOT).filter(isTemplateFile);
+  const allOffenses: Array<{ file: string; line: number; spec: string; text: string }> = [];
+  const allSyntaxErrors: Array<{ file: string; line: number; message: string }> = [];
+
+  for (const file of files) {
+    const offenses = checkFile(file);
+    for (const o of offenses) {
+      allOffenses.push({
+        file: path.relative(process.cwd(), file),
+        line: o.line,
+        spec: o.spec,
+        text: o.text,
+      });
+    }
+
+    const syntaxErrors = getTypeScriptSyntaxErrors(file);
+    for (const e of syntaxErrors) {
+      allSyntaxErrors.push({
+        file: path.relative(process.cwd(), file),
+        line: e.line,
+        message: e.message,
+      });
+    }
+  }
+
+  if (allSyntaxErrors.length > 0) {
+    process.stderr.write('Template syntax check failed. TypeScript parse errors found:\n');
+    for (const e of allSyntaxErrors) {
+      process.stderr.write(`- ${e.file}:${e.line} -> ${e.message}\n`);
+    }
+    process.exit(1);
+  }
+
+  if (allOffenses.length > 0) {
+    process.stderr.write('Template import check failed. Disallowed import specifiers found:\n');
+    for (const o of allOffenses) {
+      process.stderr.write(`- ${o.file}:${o.line} -> ${o.spec}\n`);
+      process.stderr.write(`  ${o.text.trim()}\n`);
+    }
+    process.stderr.write(
+      "\nAllowed: '@zintrust/core', '@zintrust/core/node', '@zintrust/core/start', 'node:*'\n"
+    );
+    process.exit(1);
+  }
+
+  process.stdout.write(`✓ Template import check passed (${files.length} templates)\n`);
+}
+
+main();