@zintrust/core 0.4.17 → 0.4.18

package/src/scheduler/leader/SchedulerLeader.js

@@ -0,0 +1,187 @@
+import { Env } from '../../config/env.js';
+import { Logger } from '../../config/logger.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { ZintrustLang } from '../../lang/lang.js';
+import { createAdvancedQueue } from '../../tools/queue/AdvancedQueue.js';
+import { getLockProvider } from '../../tools/queue/LockProvider.js';
+const readSettings = () => {
+    const enabled = Env.getBool('SCHEDULE_LEADER_ENABLED', false);
+    const provider = Env.get('SCHEDULE_LEADER_LOCK_PROVIDER', 'memory').trim() || 'memory';
+    const key = Env.get('SCHEDULE_LEADER_LOCK_KEY', 'scheduler:leader').trim() || 'scheduler:leader';
+    const ttlMs = Env.getInt('SCHEDULE_LEADER_LOCK_TTL_MS', 30000);
+    const renewEveryMs = Env.getInt('SCHEDULE_LEADER_LOCK_RENEW_MS', Math.floor(ttlMs / 2));
+    const retryEveryMs = Env.getInt('SCHEDULE_LEADER_LOCK_RETRY_MS', 5000);
+    const acquireTimeoutMs = Env.getInt('SCHEDULE_LEADER_LOCK_ACQUIRE_TIMEOUT_MS', 2000);
+    return Object.freeze({
+        enabled,
+        provider,
+        key,
+        ttlMs: Math.max(1000, ttlMs),
+        renewEveryMs: Math.max(250, renewEveryMs),
+        retryEveryMs: Math.max(250, retryEveryMs),
+        acquireTimeoutMs: Math.max(250, acquireTimeoutMs),
+    });
+};
+const isUnrefableTimer = (timer) => {
+    return (typeof timer === 'object' &&
+        timer !== null &&
+        'unref' in timer &&
+        typeof timer.unref === 'function');
+};
+const withTimeout = async (promise, timeoutMs) => {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        return promise;
+    let timeoutId;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timeoutId = globalThis.setTimeout(() => {
+                    reject(ErrorFactory.createConnectionError('Leader lock acquire timed out', { timeoutMs }));
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutId !== undefined)
+            globalThis.clearTimeout(timeoutId);
+    }
+};
+const resolveProvider = (providerName, ttlMs) => {
+    const name = providerName.trim().toLowerCase();
+    if (name.length === 0)
+        return null;
+    // Ensure provider is registered; AdvancedQueue wiring bootstraps lock providers.
+    createAdvancedQueue({
+        name: ZintrustLang.CLI_LOCKS,
+        connection: undefined,
+        defaultDedupTtl: ttlMs,
+        lockProvider: name,
+    });
+    return getLockProvider(name) ?? null;
+};
+const clearTimers = (state) => {
+    if (state.renewTimer !== undefined) {
+        globalThis.clearInterval(state.renewTimer);
+        state.renewTimer = undefined;
+    }
+    if (state.retryTimer !== undefined) {
+        globalThis.clearInterval(state.retryTimer);
+        state.retryTimer = undefined;
+    }
+};
+const loseLeadership = (state) => {
+    if (state.leaderLock !== null) {
+        Logger.warn('Scheduler leadership lost; stopping schedules');
+    }
+    state.leaderLock = null;
+    state.hooks?.onLostLeadership();
+};
+const ensureProvider = (state, settings) => {
+    if (state.provider !== null)
+        return state.provider;
+    state.provider = resolveProvider(settings.provider, settings.ttlMs);
+    if (state.provider === null) {
+        Logger.warn('Leader lock provider not available; scheduling disabled', {
+            provider: settings.provider,
+        });
+    }
+    return state.provider;
+};
+const tryAcquire = async (state, settings) => {
+    if (!state.started)
+        return;
+    if (state.leaderLock !== null)
+        return;
+    const provider = ensureProvider(state, settings);
+    if (provider === null)
+        return;
+    try {
+        const lock = await withTimeout(provider.acquire(settings.key, { ttl: settings.ttlMs }), settings.acquireTimeoutMs);
+        if (!lock.acquired)
+            return;
+        state.leaderLock = lock;
+        Logger.info('Scheduler leadership acquired', { key: settings.key, ttlMs: settings.ttlMs });
+        state.hooks?.onBecameLeader();
+    }
+    catch (error) {
+        Logger.warn('Failed to acquire scheduler leader lock', {
+            key: settings.key,
+            provider: settings.provider,
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+};
+const startRenewLoop = (state, settings) => {
+    if (state.renewTimer !== undefined)
+        return;
+    state.renewTimer = globalThis.setInterval(async () => {
+        if (!state.started)
+            return;
+        if (state.leaderLock === null || state.provider === null)
+            return;
+        const ok = await state.provider.extend(state.leaderLock, settings.ttlMs);
+        if (!ok)
+            loseLeadership(state);
+    }, settings.renewEveryMs);
+    if (isUnrefableTimer(state.renewTimer))
+        state.renewTimer.unref();
+};
+const startRetryLoop = (state, settings) => {
+    if (state.retryTimer !== undefined)
+        return;
+    state.retryTimer = globalThis.setInterval(() => {
+        void tryAcquire(state, settings);
+    }, settings.retryEveryMs);
+    if (isUnrefableTimer(state.retryTimer))
+        state.retryTimer.unref();
+};
+export const SchedulerLeader = Object.freeze({
+    create() {
+        const state = {
+            started: false,
+            leaderLock: null,
+            provider: null,
+            renewTimer: undefined,
+            retryTimer: undefined,
+            hooks: null,
+        };
+        return Object.freeze({
+            isEnabled() {
+                return readSettings().enabled;
+            },
+            start(newHooks) {
+                const settings = readSettings();
+                if (!settings.enabled)
+                    return;
+                if (state.started)
+                    return;
+                state.started = true;
+                state.hooks = newHooks;
+                state.provider = null;
+                // Attempt immediately; keep retrying until acquired.
+                void tryAcquire(state, settings);
+                startRetryLoop(state, settings);
+                startRenewLoop(state, settings);
+            },
+            async stop() {
+                if (!state.started)
+                    return;
+                state.started = false;
+                clearTimers(state);
+                if (state.leaderLock !== null && state.provider !== null) {
+                    try {
+                        await state.provider.release(state.leaderLock);
+                    }
+                    catch {
+                        // best-effort
+                    }
+                }
+                state.leaderLock = null;
+                state.provider = null;
+                state.hooks = null;
+            },
+        });
+    },
+});
+export default SchedulerLeader;

package/src/scheduler/state/ScheduleStateStore.d.ts

@@ -0,0 +1,27 @@
+export type ScheduleRunState = Readonly<{
+    lastRunAt?: number;
+    lastSuccessAt?: number;
+    lastErrorAt?: number;
+    lastErrorMessage?: string;
+    nextRunAt?: number;
+    consecutiveFailures?: number;
+}>;
+export type ScheduleRunStatePatch = Partial<ScheduleRunState>;
+export type IScheduleStateStore = Readonly<{
+    get: (name: string) => Promise<ScheduleRunState | null>;
+    set: (name: string, patch: ScheduleRunStatePatch) => Promise<void>;
+    list: () => Promise<Array<{
+        name: string;
+        state: ScheduleRunState;
+    }>>;
+}>;
+export declare const InMemoryScheduleStateStore: Readonly<{
+    create(): IScheduleStateStore;
+}>;
+declare const _default: {
+    InMemoryScheduleStateStore: Readonly<{
+        create(): IScheduleStateStore;
+    }>;
+};
+export default _default;
+//# sourceMappingURL=ScheduleStateStore.d.ts.map

package/src/scheduler/state/ScheduleStateStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScheduleStateStore.d.ts","sourceRoot":"","sources":["../../../../src/scheduler/state/ScheduleStateStore.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE9D,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACxD,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,IAAI,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,gBAAgB,CAAA;KAAE,CAAC,CAAC,CAAC;CACvE,CAAC,CAAC;AAIH,eAAO,MAAM,0BAA0B;cAC3B,mBAAmB;EAuB7B,CAAC;;;kBAvBS,mBAAmB;;;AAyB/B,wBAEE"}

package/src/scheduler/state/ScheduleStateStore.js

@@ -0,0 +1,27 @@
+const normalizeName = (name) => String(name ?? '').trim();
+export const InMemoryScheduleStateStore = Object.freeze({
+    create() {
+        const states = new Map();
+        return Object.freeze({
+            async get(name) {
+                const key = normalizeName(name);
+                if (key.length === 0)
+                    return null;
+                return states.get(key) ?? null;
+            },
+            async set(name, patch) {
+                const key = normalizeName(name);
+                if (key.length === 0)
+                    return;
+                const current = states.get(key) ?? {};
+                states.set(key, { ...current, ...patch });
+            },
+            async list() {
+                return Array.from(states.entries()).map(([name, state]) => ({ name, state }));
+            },
+        });
+    },
+});
+export default {
+    InMemoryScheduleStateStore,
+};

package/src/scheduler/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Scheduler types
+ */
+export type IScheduleKernel = Readonly<{
+    getContainer?: () => unknown;
+    getRouter?: () => unknown;
+}>;
+export type IScheduleHandler = (kernel?: IScheduleKernel) => Promise<void> | void;
+export type IScheduleBackoffPolicy = Readonly<{
+    initialMs: number;
+    maxMs: number;
+    factor?: number;
+}>;
+export type ISchedule = {
+    name: string;
+    intervalMs?: number;
+    cron?: string;
+    timezone?: string;
+    jitterMs?: number;
+    backoff?: IScheduleBackoffPolicy;
+    leaderOnly?: boolean;
+    handler: IScheduleHandler;
+    enabled?: boolean;
+    runOnStart?: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

package/src/scheduler/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/scheduler/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;CAC3B,CAAC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,CAAC,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAElF,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC"}

package/src/scheduler/types.js

@@ -0,0 +1,4 @@
+/**
+ * Scheduler types
+ */
+export {};

package/src/schedules/index.d.ts

@@ -0,0 +1,3 @@
+export { default as jobTrackingCleanup } from './job-tracking-cleanup';
+export { default as logCleanup } from './log-cleanup';
+//# sourceMappingURL=index.d.ts.map

package/src/schedules/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/schedules/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,wBAAwB,CAAC"}

package/src/schedules/index.js

@@ -0,0 +1,2 @@
+export { default as jobTrackingCleanup } from './job-tracking-cleanup.js';
+export { default as logCleanup } from './log-cleanup.js';

package/src/schedules/job-tracking-cleanup.d.ts

@@ -0,0 +1,4 @@
+export declare const cleanupJobTrackingOnce: () => Promise<void>;
+declare const JobTrackingCleanupSchedule: import("../scheduler").ISchedule;
+export default JobTrackingCleanupSchedule;
+//# sourceMappingURL=job-tracking-cleanup.d.ts.map

package/src/schedules/job-tracking-cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-tracking-cleanup.d.ts","sourceRoot":"","sources":["../../../src/schedules/job-tracking-cleanup.ts"],"names":[],"mappings":"AA4FA,eAAO,MAAM,sBAAsB,QAAa,OAAO,CAAC,IAAI,CAS3D,CAAC;AAKF,QAAA,MAAM,0BAA0B,kCAsCtB,CAAC;AAEX,eAAe,0BAA0B,CAAC"}

package/src/schedules/job-tracking-cleanup.js

@@ -0,0 +1,116 @@
+import { Env } from '../config/env.js';
+import { Logger } from '../config/logger.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { useDatabase } from '../orm/Database.js';
+import { Schedule } from '../scheduler/Schedule.js';
+const toSqlDateTime = (value) => value.toISOString().slice(0, 19).replace('T', ' ');
+const assertSafeTableName = (raw, label) => {
+    const value = raw.trim();
+    if (value.length === 0)
+        throw ErrorFactory.createGeneralError(`${label} table is empty`);
+    // allow db.schema.table and underscores
+    if (!/^[A-Za-z0-9_.]+$/u.test(value)) {
+        throw ErrorFactory.createGeneralError(`${label} table contains invalid characters: ${value}`);
+    }
+    return value;
+};
+const cleanupJobTrackingBatch = async () => {
+    const connection = Env.get('JOB_TRACKING_DB_CONNECTION', 'default');
+    const jobsTable = assertSafeTableName(Env.get('JOB_TRACKING_DB_TABLE', 'zintrust_jobs'), 'Jobs');
+    const transitionsTable = assertSafeTableName(Env.get('JOB_TRACKING_DB_TRANSITIONS_TABLE', 'zintrust_job_transitions'), 'Transitions');
+    const retentionHoursRaw = Env.get('JOB_TRACKING_CLEANUP_RETENTION_HOURS', '').trim();
+    const retentionHours = retentionHoursRaw.length > 0 ? Number.parseFloat(retentionHoursRaw) : Number.NaN;
+    const retentionDays = Math.max(1, Env.getInt('JOB_TRACKING_CLEANUP_RETENTION_DAYS', 30));
+    const batchSize = Math.max(100, Env.getInt('JOB_TRACKING_CLEANUP_BATCH_SIZE', 5000));
+    const retentionMs = Number.isFinite(retentionHours) && retentionHours > 0
+        ? retentionHours * 60 * 60 * 1000
+        : retentionDays * 24 * 60 * 60 * 1000;
+    const cutoff = new Date(Date.now() - retentionMs);
+    const cutoffSql = toSqlDateTime(cutoff);
+    const db = useDatabase(undefined, connection);
+    const transitionRows = await db
+        .table(transitionsTable)
+        .select('id')
+        .where('transitioned_at', '<=', cutoffSql)
+        .orderBy('id', 'ASC')
+        .limit(batchSize)
+        .get();
+    const transitionIds = (transitionRows ?? [])
+        .map((row) => Number(row.id))
+        .filter((id) => Number.isFinite(id))
+        .map((id) => Math.floor(id));
+    if (transitionIds.length > 0) {
+        await db.table(transitionsTable).whereIn('id', transitionIds).delete();
+    }
+    const jobRows = await db
+        .table(jobsTable)
+        .select('id')
+        .where('status', '=', 'enqueued')
+        .where('updated_at', '<=', cutoffSql)
+        .orderBy('id', 'ASC')
+        .limit(batchSize)
+        .get();
+    const jobIds = (jobRows ?? [])
+        .map((row) => Number(row.id))
+        .filter((id) => Number.isFinite(id))
+        .map((id) => Math.floor(id));
+    if (jobIds.length > 0) {
+        await db.table(jobsTable).whereIn('id', jobIds).delete();
+    }
+    return {
+        retentionDays,
+        cutoffIso: cutoff.toISOString(),
+        batchSize,
+        deletedTransitions: transitionIds.length,
+        deletedJobs: jobIds.length,
+    };
+};
+export const cleanupJobTrackingOnce = async () => {
+    const result = await cleanupJobTrackingBatch();
+    Logger.info('Job tracking cleanup batch completed', {
+        retentionDays: result.retentionDays,
+        cutoff: result.cutoffIso,
+        deletedTransitions: result.deletedTransitions,
+        deletedJobs: result.deletedJobs,
+        batchSize: result.batchSize,
+    });
+};
+const enabled = Env.getBool('JOB_TRACKING_CLEANUP_ENABLED', false);
+const intervalMs = Env.getInt('JOB_TRACKING_CLEANUP_INTERVAL_MS', 6 * 60 * 60 * 1000);
+const JobTrackingCleanupSchedule = Schedule.define('jobTracking.cleanup', async () => {
+    const maxBatches = Math.max(1, Env.getInt('JOB_TRACKING_CLEANUP_MAX_BATCHES', 1));
+    let batchesRun = 0;
+    let deletedTransitionsTotal = 0;
+    let deletedJobsTotal = 0;
+    let retentionDays;
+    let cutoffIso;
+    let batchSize;
+    for (let i = 0; i < maxBatches; i += 1) {
+        // Bounded sequential batches are intentional; we want predictable DB load.
+        // eslint-disable-next-line no-await-in-loop
+        const result = await cleanupJobTrackingBatch();
+        batchesRun += 1;
+        deletedTransitionsTotal += result.deletedTransitions;
+        deletedJobsTotal += result.deletedJobs;
+        retentionDays = result.retentionDays;
+        cutoffIso = result.cutoffIso;
+        batchSize = result.batchSize;
+        if (result.deletedTransitions + result.deletedJobs === 0) {
+            break;
+        }
+    }
+    Logger.info('Job tracking cleanup run completed', {
+        retentionDays,
+        cutoff: cutoffIso,
+        batchSize,
+        batchesRun,
+        maxBatches,
+        deletedTransitionsTotal,
+        deletedJobsTotal,
+    });
+})
+    .intervalMs(intervalMs)
+    .withoutOverlapping({ provider: Env.get('JOB_TRACKING_CLEANUP_LOCK_PROVIDER', 'memory') })
+    .enabledWhen(enabled)
+    .build();
+export default JobTrackingCleanupSchedule;

package/src/schedules/log-cleanup.d.ts

@@ -0,0 +1,3 @@
+declare const LogCleanupSchedule: import("../scheduler").ISchedule;
+export default LogCleanupSchedule;
+//# sourceMappingURL=log-cleanup.d.ts.map

package/src/schedules/log-cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-cleanup.d.ts","sourceRoot":"","sources":["../../../src/schedules/log-cleanup.ts"],"names":[],"mappings":"AAIA,QAAA,MAAM,kBAAkB,kCASd,CAAC;AAEX,eAAe,kBAAkB,CAAC"}

package/src/schedules/log-cleanup.js

@@ -0,0 +1,15 @@
+import { Env } from '../config/env.js';
+import { Logger, cleanLogsOnce } from '../config/logger.js';
+import { Schedule } from '../scheduler/Schedule.js';
+const LogCleanupSchedule = Schedule.define('log.cleanup', async () => {
+    try {
+        await cleanLogsOnce();
+    }
+    catch (err) {
+        Logger.error('Log cleanup schedule failed', err);
+    }
+})
+    .intervalMs(Env.getInt('LOG_CLEANUP_INTERVAL_MS', 3600000))
+    .enabledWhen(Env.getBool('LOG_CLEANUP_ENABLED', Env.getBool('LOG_TO_FILE', false)))
+    .build();
+export default LogCleanupSchedule;

package/src/scripts/GenerateEnvArtifacts.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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
+ */
+export {};
+//# sourceMappingURL=GenerateEnvArtifacts.d.ts.map

package/src/scripts/GenerateEnvArtifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GenerateEnvArtifacts.d.ts","sourceRoot":"","sources":["../../../src/scripts/GenerateEnvArtifacts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/src/scripts/GenerateEnvArtifacts.js

@@ -0,0 +1,171 @@
+/**
+ * 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.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import fs from '../node-singletons/fs.js';
+import * as path from '../node-singletons/path.js';
+const ROOT_DIR = path.resolve(process.cwd());
+const GENERATED_MARKER = 'Generated by src/scripts/GenerateEnvArtifacts.ts';
+const walkDir = (dirAbs) => {
+    const out = [];
+    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) => fs.readFileSync(fileAbs, 'utf8');
+const uniq = (arr) => Array.from(new Set(arr));
+const parseEnvUsages = (content) => {
+    const out = [];
+    // 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) => {
+        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) => {
+            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) => {
+    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) => {
+    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) => {
+    const sortedKeys = keys.toSorted((a, b) => a.localeCompare(b));
+    return sortedKeys.join('\n') + '\n';
+};
+const writeIfChanged = (fileAbs, next) => {
+    const prev = fs.existsSync(fileAbs) ? fs.readFileSync(fileAbs, 'utf8') : '';
+    if (prev === next)
+        return;
+    fs.writeFileSync(fileAbs, next, 'utf8');
+};
+const shouldOverwriteEnvExample = (envExampleAbs) => {
+    if (!fs.existsSync(envExampleAbs))
+        return true;
+    const prev = fs.readFileSync(envExampleAbs, 'utf8');
+    return prev.includes(GENERATED_MARKER);
+};
+const main = () => {
+    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.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=TemplateImportsCheck.d.ts.map

package/src/scripts/TemplateImportsCheck.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TemplateImportsCheck.d.ts","sourceRoot":"","sources":["../../../src/scripts/TemplateImportsCheck.ts"],"names":[],"mappings":""}