@zintrust/core 0.1.28 → 0.1.29

package/src/scheduler/ScheduleRunner.ts

@@ -1,219 +0,0 @@
-/**
- * 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

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

package/src/scheduler/types.ts

@@ -1,18 +0,0 @@
-/**
- * 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

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

package/src/schedules/log-cleanup.ts

@@ -1,21 +0,0 @@
-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

@@ -1,203 +0,0 @@
-/**
- * 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

@@ -1,180 +0,0 @@
-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();